advertisement
advertisement
  • 10.07.14

Five Ways To Write Better Technical Documentation

Having trouble writing technical documentation? Here’s some advice from Hacker News.

Five Ways To Write Better Technical Documentation
[Photo: Flickr user Tim Lucas]

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.

advertisement

1) Be Clear And Concise

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)

2) Write Good Code

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.

3) Read Other Documentation

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:

– Django: https://docs.djangoproject.com/en/1.7/
– Symfony: http://symfony.com/doc/current/book/index.html
– Rails: http://guides.rubyonrails.org/ and http://api.rubyonrails.org/

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.

advertisement

4) Show Examples

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

5) Sell Your Code

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.

About the author

Tyler Hayes is a Southern California native, early technology adopter, and music enthusiast.

More

Video