Technical documentation can have a huge impact on the success of any platform. So when a Hacker News user asked “How do I write good documentation?” the response was swift. The user’s particular need was for a PHP framework, but the advice and recommendations provided by commenters should be useful to anyone looking for similar help. Here are five responses that stand out as good take-aways for anyone in the same situation.
Figure out who the documentation is meant for and speaking clearly to that user. From user junto:
Make it well-structured, consistent and concise.
One of the best examples I’ve come across is the documentation for Rackspace Cloud Files: (PDF)
Writing good documentation is assisted by writing good code in the first place. The better the code, the less work it should take to document it.
User martianE points out the different role documentation can play with clearly written code.
In fact the best documentation I’ve seen (say flask, django) most of the documentation acts as support for reading the code.
This is backed up by user znt:
Simpler & more succinct code is also easier to document.
How do you become a better writer? Read more. It’s common advice for all writers, which applies to those writing code documentation as well. User jschulenklopper adds links to other documentation for some extended reading.
Discover what choices the writers made (implictly) and what works for you w.r.t. structure, clarity, completeness, conciseness. In your case, look for documentation of other (web) frameworks with a large audience, for example:
User atsaloli also added a link to the article “The 7 Rules For Writing World Class Technical Documentation,” which confirms a lot of the advice commenters were giving.
People looking to learn new languages or different development techniques are also looking for good examples of the code in use. While some people like to read their way through the process, others prefer to get hands-on as quickly as possible.
From user progx:
php-documentation is really beginner friendly because of the small examples and the comments
Code documentation doesn’t have to be dry and boring as pointed out by user chatmasta. For developers interested in the code with the possibilities of using it in the future, don’t forget to highlight some main features and show them why they should be using it too.
Don’t lie or use gimmicky methods for enticing users, but make a TL;DR intro, which quickly gets people interested.
From user samelawrence:
Even once you’ve managed to convince a developer to use your tool, he or she may need to convince their management of the same thing, so good documentation can provide them with the “sales” points they need to get your framework adopted by their company / team / project lead.
Good documentation not only informs and excites the end user of the tool, but should also provide a basis of value for any other stakeholders in the outcome of its usage.