Writing good technical documentation, part 2
Joel Spolsky has an excellent post on the role of the program manager. I work with program managers, so I read through it comparing his descriptions with the PMs I've known. Then I got to the part on functional specifications and my interest level jumped a few notches.
Because the spec is -- or can be -- one of the technical writer's best tools.
By coincidence, my manager recently asked us to jot down what we considered to be characteristics of a good spec for a software feature (from a writer's POV). My contribution:
- What it is
- Why it is
- What it does
- How it works
- When it does it/is used
- Who uses it
That's not too much to ask for, is it?
If you're the writer and you're not involved in your team's spec reviews, ask to be included. Read the specs, ask questions, make suggestions. Remember, whatever they develop from it, you'll have to explain to the customer.
(As a side note, that brings to mind one quality that a good tech writer must have -- the willingness to ask "dumb" questions. If you don't ask the question because you're worried that it might make you look silly, you're doing yourself, the customer, and the team a disservice.)
Back to specs. The spec sets the stage for the story that your documentation will tell. From the specs, you should be able to start crafting the high-level design for the docs: what the user will be doing and what they need to know to do those things, what method and organization for the documentation will be most useful for that type of information.
If the specs you work with don't include user interface mock-ups, finagle your way into those UI meetings and reviews as well. Look at each screen with the question "how am I going to explain this?" Be the customer's advocate: "Why am I clicking Next three times?"