Ask HN: How do I write good documentation?

Start off by reading documentation, preferably good. It's not easy, but just as everything else you will get better with practice so you'll have to just write. You can always go back and revise just like your code!

This is personal, but I taught myself how to code, before the internet, and with barely any books. One thing that made, for example, the PHP documentation a lot easier to read vs. Perl was: examples

On an API level, don't just explain what things do, but how to use it, what is the intention behind a particular call or method, and how it integrates with other pieces of the environment. If there are best practices, this is the place to call them out. And it does not need to be a tutorial, but if the class calls for a "usage sample", that is perfect for the documentation.

Pick on these: 1) What decisions did you take for the implementation? 2) What tradeovers are made (this is written like this because ...) 3) How is it supposed to be used 4) What is the common pattern for accessing the resource (instantiate it, factory, singleton, dependency injection?) 5) How does it relate with the rest of the codebase?

Now, this is PHP, but on other languages... 6) Is it Thread-Safe? 7) How cheap is it to instantiate a new object of that type?

http://docs.writethedocs.org/writing/beginners-guide-to-docs... might be useful

Here is a guide to documentation I wrote a little while back: http://brikis98.blogspot.com/2014/05/you-are-what-you-docume...

The most important thing is to make the API design not only easy to use, but also slightly defensive. If people should doing things one way, guide them toward that in the API, and make it harder for them to do the wrong thing. A lot of documentation can be made redundant in this manner.

As for the documentation itself, I know of no good way to put yourself in the shoes of someone who does not know your API - you are just too familiar with it to be a good judge of the documentation. Instead, test it. Get others to read it and try to accomplish particular tasks, invite feedback (and be open to it - if they get something wrong it's not their fault, it's yours, they're the experts in how useful this documentation is so listen to them), and iterate.

Good luck!

Imagine you are sitting next to a person who will be taking over your code. How would you explain your code to him/her? Just write down that imaginary conversation and very likely you will have the best documentation of your code.

I enjoyed both "The TeXbook" and "The METAFONTbook" as great documentation. It helps that they're literately programmed, obviously, but you can't go wrong reading Knuth's commentary.

Here's a really great resource on how to make your project accessible: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-you...

If you only read one link from that page, make it this one: http://jacobian.org/writing/great-documentation

Those two pages are well worth your time.

I cannot stress this enough: write good code! Any decent code editor now jumps you to the source of the code you're calling allowing you to quickly see what the code does, what parameters are needed, etc.

In fact the best documentation I've seen (say flask, django) most of the documentation acts as support for reading the code.

Simpler & more succinct code is also easier to document. So if you have functions that are several LOC long, simplifying / dividing them into smaller functions can be helpful.

talking about tools ...which can make your documentaion look better ....go for sphinx (python based) .. excellent tool...usd it...loved it !!

You stop writing code for a 'week'. Don't 'touch' the codebase during that time. Come back after that duration has passed, re-discover the code and write the documentation then.

Especially in teams, one thing I've found that helps in documentation is standards and templates. If everyone knows exactly what to document, how to document it, and where the documentation lives then it's much more likely to get done and done well.

Start with a minimal set of standards and templates and build up, rather than over-engineering and not getting anything done.

another small guide : http://docs.writethedocs.org/writing/beginners-guide-to-docs...

Documentation can end up sucking up a large amount of your time. It's also very easy for documentation to get out of date.

It's therefore useful to tie your documentation to the code itself:

1. Generate documentation from the code where appropriate.

2. Automatically test examples in your documentation each time you regenerate it.

Start by having a one-line description saying what every file, class, method, function, etc., is for. Where needed, expand on what parameters are expected, and give examples of usage. This is the API reference and it can be automatically extracted from the source code if it is part of comments.

For a getting started / user guide, give a higher level description of how components tie together and show end-to-end usage examples. The key here is to be succinct but include all the information that a new user will need to get started. Whenever someone asks a question, this is a good sign that information should be added to the docs.

First you should decide who the intended audience of your documentation is. Who are you trying to help, and what are you trying to help them do?

Then, partition your mind into two halves. The first half contains everything you know about the project, and the second half contains everything your imaginary new reader knows, which may be nothing.

Identify each difference between these two bodies of knowledge and, starting with the largest and simplest, write down what the reader needs to know in order to transition from one state of mind to the other, in as succinctly a way as possible.

If you start rambling, go back and edit.

I find this works for explaining many things, not just software projects.

Just keep answering these questions as appropriate:

  - What is this?
  - What is it for?
  - How do you use it?

And/or maybe:

  - What's going on?
  - Where do we go from here?
  - What are we trying to accomplish?
  - How do we accomplish it?

In other words, think about everything from the user's perspective.

Make it well-structured, consistent and concise.

One of the best examples I've come across is the documentation for Rackspace Cloud Files: http://docs.rackspace.com/files/api/v1/cf-devguide/cf-devgui...

Steal someone else's doc. Someone who did a good job. (CC-SA licensed or similar so its legal) (And edited to add, doing the right/moral thing wrt attribution and thanks, is important, not just doing the absolute minimum that whatever legal license requires)

Not kidding. Its an effective checklist and provides decent balance, at least a first guess at checklists and balance. Think of it like a development framework... for docs.

A really difficult startup problem (aka a good one) would be automation for doc writing. When you code its really easy to have automated syntax checkers and testing systems and A/B binary search algos to scan thru a git repo to find when a bug was introduced... and when writing docs its still the 1980s, maybe 1990s, you've got a spell checker and maybe a grammar checker and possibly some kind of "grade level analyzer" that just looks up and calculates average syllable length of words. There must be something better out there.

There have been no shortage of historical attempts at inline doc generators and template systems and markup language for technical docs. However, none have revolutionized the world, at least not yet.

(Edited to add, just caring about this issue puts you ahead of the pack, which is either a very optimistic comment WRT you, or very pessimistic comment WRT everything else on average... Glass half full or half empty LOL)

Actually use the framework (every feature) and write down everything you needed to know to use it. Really, the more time you put into something the better it will be, so just make a good effort and it will be good.

Read the book: Writing Software Documentation: A Task-Oriented Approach Thomas T. Barker, Texas Tech University ISBN-10: 0321103289

You have just found a hard problem. :) More seriously I find depending on the users needs, different documentation are needed. Documentation for beginners. Specifications which include any gotcha that anyone ever tells you, also what it doesnt do that people try. And how-tos to get stuff done. And never believe anyone who tells you the code/test documents itself. It doesn't. It just means your trying to get the users to document it for you. Which isn't terrible if you have to do it to lower cost, but lowers uptake, and gives a worse experience.

You are not only writing documentation. You are also writing sales copy for your framework. Recognize that developers will come to your API docs with two possible mindsets:

1) Evaluation stage: Developer arrives at API docs with goal of determining whether framework solves problem within unique set of constraints. Expect him to skim docs, searching for keywords related to constraints, and/or any examples similar to problem.

2) Implementation stage: Developer has settled on your framework (at least initially), and is ready to build first project. Will either complete project, or abandon framework, depending on technical quality of your docs.

These two mindsets represent two components of a sales funnel. On the docs landing page, your primary goal should be converting developers from Mindset #1 --> Mindset #2. If you look at popular docsets, you'll notice that the intro pages tend to read like sales pages. Why should you use this framework? What are some popular production implementations? Any cool examples?

Deeper in the docs, you simply need solid technical documentation. Other comments here have great tips. Just keep in mind that Mindset #1 will barely skim these areas of your docs, but will definitely consider them briefly.

So, in brief:

1) Sell developers.

2) Write good technical docs.

  Minuteman Framework
  
  !!! Gets your missiles launched in seconds!
  !!! Produce reports of completed strikes!
  !!! Makes a great pasta salad!

  Minuteman Framework

  !!! Provides a C library and python, perl and ruby bindings for assembling, scheduling, executing, and reporting on minuteman launch capabilities for a variety of platforms. 
  !!! Supports only ARM and SPARC architectures.
  !!! Requires 3 active nodes on 5 different networks for high availability.
  !!! No REST API support.

> How do I get better at writing documentation?

Read other documentation. 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/