In a recent post, I talked about having documentation design reviews. Yesterday, I showed my team a new project I’m working on. I was trying out a new approach, the idea behind which was good. But the team’s feedback helped me turn it into something better—and visually simpler.
Our interaction design group holds regular design reviews. In these meetings, they show each other what they’re coming up with for the projects they’re working on and give each other feedback. A designer will generally put his designs up for scrutiny before he gets very far in his designs so that the others can ask questions and suggest additional factors to consider.
This is a great practice for technical communicators. This field involves designing the way a user interacts with content. I may be designing electronic or print materials, but holding reviews with fellow technical communicators before I go far down a particular path could only improve my thinking and save me work later. As with most things, the more eyes you have to give perspective on something, the better of it will be. We plan on beginning this in our team pretty soon.
We have a customized flavor of Agile development, and today as I was talking to one of the program managers about the next few cycles of work in a particular project, he said that the work in the last cycle or two was not yet defined. That’s fine; at least in our version of Agile, the work that was defined generally at the beginning is solidified as we go. Development is planned on an iteration-by-iteration (or sprint-by-sprint in some vocabularies) basis and more broadly on a cycle-by-cycle basis. A cycle contains several iterations of work, and the idea is to have a body of code that can be released to and used by the customer at the end of the cycle. The interaction designers prototype at least one cycle ahead of development.
The manager hopes that most of the new development work will be done at the end of the second-to-last cycle. As he talked, I got a little idea: What if the last cycle of an Agile project were reserved for bug fixes? We have hardening periods before the release for fixing bugs and for the testers to make sure they’ve exercised and proven the functionality that was developed at the end of the cycle. But what about an overall hardening cycle for the bugs that haven’t yet been addressed throughout the entire project?
This would benefit the team and the customer, but I wouldn’t be talking about this if I didn’t think it could benefit me, the technical communicator.
I was thinking about this yesterday and ended up talking to Tom about it today. We work on projects that have asked similar things of us, but in other cases, our constraints are quite different. One example is security.
Let me illustrate. One Web application may allow users to complete a process that is not in any way sensitive in and of itself. So the help content for that application also is not sensitive, so it’s not problematic for it to be on a publicly accessible server. Even if the data that the users enter in the application can be sensitive or private, you don’t know what they’re entering by reading the help, so there’s no problem.
On the other hand, another application may help users in completing a sensitive process. By association, then, because the help describes that process, it is sensitive. I have found that generally, the projects I work on require more security than Tom’s.
This creates a challenge for our team as we work on standard and best practices.
Our team has been putting together some plans for a day out of the office. I’m not talking about taking a day off and getting together as a team to see a movie, but rather going somewhere to talk strategy and best practices. We’ll be working, but it will be a laid back, day-long discussion and brainstorming session.
Why not just have a meeting in a conference room? Even have the caterers bring in lunch? Because sometimes, it’s helpful to get in a different environment even for one day for a fresh perspective on things. In my opinion, if you spend day after day without any changes, you’re less stimulated. Your brain runs the same circles, and it’s hard to take a fresh approach.
We’ve been taking a step back and examining our documentation approach at work. It’s easy, and there is still time to change things, because our team is small. We’re not set in our ways, and we haven’t had an approach or tools dictated to us. One of the main concerns we have is the big disconnect between users and the project team.
Sure, there are interaction designers and business analysts who gather requirements and translate them into user-friendly and user-desired interfaces. At least they try. Many times, even the key stakeholders’ views don’t coincide exactly with the users’ views. It’s a challenge when you’re trying to meet the needs of users who are scattered across the world.
However, as Tom Johnson has brought to our team’s attention, Web 2.0 offers a way for technical communicators to increase their importance as a point of contact between users and the project team. (He posted recently about his experiments with SharePoint to accomplish this goal.) Now I’m not blowing a trumpet and saying that Web 2.0 is a cure-all for the tech writer’s ailments. But there are advantages to it.
One of the challenges that technical communicators in the category of documentation face is keeping up with changes made to the product as it is developed. In some environments, specs or requirements are set out at the beginning, but in others—particularly in some software development companies—the customer, project management, or developers may alter the original set of requirements because of unforeseen circumstances, such as technical limitations or time constraints.
This challenge may be aggravated when the technical writer remains unapprised of such changes. Personally, I have signed in to a software application and seen user interface tweaks that affect the documentation in no small measure: images, procedures, descriptions; you get the picture. But I have found a few ways to get into the developers’ consciousness so that I’m not taken by surprise.
The views expressed in this blog and the responsibility for them belong to its author.
If you'd like to add this site to your blogroll, simply drop me a note to let me know.
Subscribe to the Journals