Writers As Designers

In too many offices, the documentation specialists are isolated from the rest of the team. The programmers usually think of documentation as nonsense, and don't think that writing clear English is a skill even though they can't do it themselves. The doc specialists are frustrated by confusing software which nobody can seem to explain, and insulted by programmers who hold in contempt anyone who can't write code. Since both sides dislike each other it's easier to not talk. This is too bad, because a writer's skills are necessary to program well. Writers can contribute in many more ways than just putting together manuals. Every step of a programming project can be improved by having writers as a part of the team.

A project begins with listening to what users want, and then trying to translate that into a consistent story. If this isn't done, or is done badly, it's likely that the users will be missing things they want, require extra training to understand the system, and possibly reject the system out of hand. Building a system out of the user's language forestalls these problems. This skill, of translating an undifferentiated mass of ideas into a narrative is what writing is. Doing this requires no technical knowledge, just an ability to listen and think, and then translate that into a system. This is an area that writers shine in.

Including writers on the design team can also help because they aren't programmers. Programmers can get bogged down in technical detail to the detriment of the design. Also programmers have a tendency to make up technical excuses for being lazy. Many times programmers will settle for a poor design because a good one seems like too much work. Another thing programmers are lazy about is the look and feel of applications, mostly because fixing cosmetic problems is usually arduous and boring. Having someone on your team that can push back against that mentality is important. It keeps the team honest.

Writers help with the design in other ways. When a writer finds something difficult to document, that's a warning sign. It usually means you need some clarification from the users, or the programmers need to go back to the drawing board and think up something that's easier to explain. Forcing writers to document things that are confusing or ambiguous means forcing bad design on your users. But if writers are full members of the team, they can tell you about these problems before the users see them.

Writers are also part of the test team. Every piece of documentation is also a test plan. The first thing a writer should do after finishing a piece of documentation is fire up the application and test what they've written. If things don't go as they should, that's another warning sign. Either the documentation needs to be rewritten to explain extra steps, the program needs to be fixed or the design needs to be revisited. In any case, the mismatch between documentation and code lets you know that some more work needs to be done.

Writers should be full members of programming teams. They can contribute to the design of the project, and are able to spot problems before the users see them. If writers are considered full team members, they'll be more willing to share problems they're having, which many times are signs of deeper problems in the application. Writers should be brought out of their isolation and into the team.