It's incumbent on everyone in a development project to share knowledge efficiently by getting key points across economically. If you're not comprehensive, coherent, correct and concise, you risk other people missing your point because they never heard about it, couldn't follow it, didn't believe in it or lost interest in it, and that leads inexorably to extra costs.
In that spirit, the meat in this post is that you should endeavour be as open as possible, full in description and slight in length. When these are in conflict, strive to remove the need for fullness. If you must be full, then structure your content accordingly.
Software teams are often dislocated in place but even if not they will be dislocated in time for some of the time. Documentation (including wikis, bug reports etc) provide a form of collaboration and knowledge sharing between the author(s) and the reader(s). When the readers are also authors it's a more involved collaboration and when a document is the primary mode of communication too there's greater need for completeness, efficiency and clarity. Like all collaboration there is cost and because generally there are fewer authors than readers, it's generally cheaper for the writer to pay up front.
Here's some of the things I try to keep in mind when I'm writing for work.
Dialogue vs monologue. In a conversation the listener can interrupt but on the page it's up to the writer to provide context. If there's insufficient context your readers won't know what you're talking about and it will cost them time and effort to divine it - and they might not get it right.
If you say the same things in multiple places you create a maintenance headache or a breeding ground for inconsistency. As the Dev team almost have it, Don't Rewrite Yourself. Instead cross-reference or provide hyperlinks when possible to give context.
Avoid anaphora with no obvious antecedents in the context. So "in the meeting it was decided that ..." might be OK for you and the attendees today but what about someone else next year? If it's not important that it was a meeting don't say. In any case, give the important information which is, e.g. "The CTO said today that ..." Likewise, "elsewhere" "above" or "below" should be replaced with a link to the place. Documents are dynamic so don't just assume the layout or structure will persist.
You can avoid the need to explain terms if you just don't introduce them. Use the standard name for the thing you're referencing and do so consistently. Try to avoid even changing its spelling or capitalisation because, to readers, differences raise questions. Don't create implicit definitions either - when you need a new name for something then be explicit, once, clearly.
If you're digressing, and the digression is useful but not relevant, move it to somewhere else and reference it.
Group related points together. They provide and reinforce context.
Don't describe something when you can easily show it and don't overshow just because you can. If you have log or other trace then use it sparingly. Show the key lines with timestamps and full error messages and provide the rest in a link.
Screenshots are good. When they're good screenshots. A verbal description that leaves an exercise for the reader is wasteful of a reader's time. If you have many readers, it's wasteful many times. A tight text and a screenshot with a red circle round the problem is cheap and useful.
Justify your conclusions, but as briefly as possible. Resist the temptation of pointing the reader at a starting point from which they could reason to the conclusion themselves, although do point to that starting point. If not, you're selling yourself short and your reader long.
Don't play your cards close to your chest. You're in a team and what you think is irrelevant, impossible or ignorable may be none of those things to someone else on the team.
Write short, declarative sentences and short paragraphs. Don't be afraid to restructure and cut what you've written before you commit it.
Use indentation, font styles, bullets, headers and other formatting when they're useful for explanation or clarity. Avoid them otherwise - they're just a visual distraction. Use tables or diagrams when they can compress or simplify lists or prose. But apply the same principles to them as you would to writing - be precise and concise.
Sometimes you do need to write more, but in that case, structure so that the key stuff is first, like a journalist would. Key points up front; context and detail later. Try to avoid putting your intepretation in front of the facts. For example, start with the problem not with a question about how to implement one possible solution.
None of this applies to blog posts, of course.
Image:http://flic.kr/p/5fT3A8
Comments
Post a Comment