Nobody appreciates good documentation. Instead, good documentation is simply there, existing, answering questions, solving problems, and quietly serving its purpose. The bad—or the complete lack of—documentation, on the other hand, you notice.
In open source communities, software and the personalities behind it tend to get the glory, while documentation—if it exists—is an afterthought, which really is too bad. The power of good (or bad) documentation shouldn't be ignored.
Today we're kicking off Doc Dish, a new community column dedicated to documentation, and we're looking for contributors.
Our first article is by Rich Bowen, based on one of his conference talks. After I saw him give the talk recently at ApacheCon in Austin, I resisted the urge to stand up and clap. Instead, I asked him to help us kick off our column, which led to his article: RTFM? How to write a manual worth reading.
As you'll see in his article, Rich doesn't have documentation training per se, but he has been creating and improving docs for a couple of decades and has given the topic a lot of thought. He explains how documentation says a lot about your project and community. Even well-written documentation, for example, can send a message about what kind (not kinds) of people work on it. And he shows how something as small as an error message falls under the documentation umbrella. His article also offers a bunch of tips and links to additional resources, so be sure to check it out.
If you or your project would like to contribute to the new documentation column, email us an article proposal, with a brief outline and author bio. Let us know if you have questions about how to submit an article or if you need more information. And remember: Good documentation is good thinking.
Dish
This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us at open@opensource.com for more details.
Comments are closed.