RTFM? How to Write a Manual Worth Reading


There’s common wisdom in the open source world: Everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are. But the truth is that there are lots of people who want to write the docs. We just make it too hard for them to participate. So they write articles on Stack Overflow, on their blogs, and on third-party forums. Although this can be good, it’s also a great way for worst-practice solutions to bloom and gain momentum. Embracing these people and making them part of the official documentation effort for your project has many advantages.

Unlike writing fiction, where the prevailing advice is just start writing, when it comes to technical writing, you need to plan a bit. Before you start, there are several questions you should ask.


The first of these is who?. Who are you writing to? Some professional tech writers create personas so that when they are writing, they can think to themselves, “What would Monica need to know in this situation?” or “What kind of problem is Marcus likely to have around this topic?” and then write accordingly.

Read more at OpenSource.com