You know what it's like to not understand how some silly software needs to be used. Ideally, it should be obvious, but in practice, you'll want to read at least some documentation, if only to have some general understanding of what the software is for.
Sometimes you yourself will have to write documentation or other prose about your software. It might not be user-oriented documentation; it might be a project proposal, an architecture overview, or an incident report on how you dealt with a security problem in the code.
All hackers (programmers, software developers, system administrators) need to write prose. It's inevitable, so it makes sense to learn how to do it without too much pain. This article gives a brief introduction to the topic, from the assumption that you're a programmer.
You're a programmer. You should probably approach writing as you would programming.
Overview of documentation development
Although all the details are different, writing as a process can be similar to programming.
- Define acceptance criteria and scope.
- Specify relevant user personas and use cases.
- Write a prototype document.
- Get your text reviewed and user-tested.
- Make changes based on review feedback.
- Iterate until good enough.
Acceptance criteria and scope
You should decide what your document is for. What should it cover? What does it not need to cover? When is the document good enough that you can stop writing it?
These are similar to the question you'd decide on when writing some software. The difference between a writer and a programmer is that the writer finds it easier to answer these questions about a document and a programmer about software.
As an example, this blog post itself is meant to cover basics of writing documentation. It won't go into a deep discussion into tooling. It's done when I think it's going to be useful to read by someone who dreads writing any prose at all.
User personas and use cases
Just as for software, documentation has target users. In writing, this is often expressed as "target audience". Who are the people you want to read the documentation? The sullen answer of "don't know, don't care, don't wanna, not gonna" isn't useful here. If you really aren't going to write anything, then you can stop reading. If you really are going to write, you need at least a rudimentary answer.
In addition, use cases can also be relevant for documentation. For example, a manual for a program might have use cases such as "how to start the program", "how to configure the program", and "what does this error message mean?".
A prototype document
A software prototype is a rough sketch of what the program might do when it's finished. The first prototype document should be an outline, perhaps with a paragraph of text for each chapter or section. When someone reads it, they get an idea of what the finished document will be like.
Later document prototypes will add more text. There might be many iterations, and each might fill in a chapter or two.
Get your text reviewed and user-tested
Code review is quite efficient at finding problems. Text review is even more efficient. User-testing is also useful for documentation: you get people to read your text and ask them questions to see if they understood things correctly.
If you do many iterations, you'll want to find new readers every now and then. Fresh eyes are better.
Make changes based on review feedback
This is a no-brainer.
Actually, no, it isn't. Sometimes feedback is ambiguous, or different people give conflicting feedback. Or they're utterly, totally wrong about semicolons; they're not the evil of our times, after all.
You do your best. The next iteration will show if you made things better or not.
Sometimes feedback is soul-crushing. People may say unpleasant things about the thing you've spent days or weeks or months to make. Same thing happens with code, of course. If you can, try to see if they have a kernel of useful truth that you can extract and make use of, but otherwise just ignore those people in the future.
Iterate until good enough.
With code, iteration is fairly straightforward. With text, you probably want to iterate fewer times to avoid exhausting your readers.
However, you should always feel free to treat each iteration as a draft, with the intention of making the next one better than the current one.
Random points about writing
Writing text is much less painful if you are good at typing. Touch typing really helps. It helps with code as well, but not nearly as much.
It may help you to use your usual tools: your text editor, version control system, etc, instead of a WYSIWYG word processor. Familiarity helps, and it helps not getting angry at all the ways in which modern word processors get in your way by trying to be helpful. I'm being opinionated here: if you like using a word processor, by all means do.
Don't worry about layout, typography, pagination, etc. Don't even worry about length, since you're writing digital content, and are not bound by limitations of the physical world. Instead, worry about the structure of your document.
Don't worry about writing perfect prose. It's useful to use a spelling checker, but you can do that after you've got the text done otherwise. Don't worry about using fine or fancy language, as you might find in some world-class literature; it's perfectly OK, and often preferably, to only write simple sentences.
You're writing software documentation. Don't worry about style, unless
you want to. ABC is the goal: accuracy, brevity, and clarity. You can
add humour, if you want to, but that's a squirrel, sorry, personal
choice. Completely optional. If you're overcoming a reluctance to
write, it's important that you write, not that you entertain.
You may benefit from the Cory Doctorow Method of writing. After you have an outline, write a draft of one section. If your sections are of reasonably small scope, it might take you half an hour per section, which you can do in one sitting. Repeat every day, and in what feels like no time at all, you'll have a big manual.