Ask HN: How to document your *project*

[dvd0101]

Hi, I'm looking for online resources of any kind (articles, blogs, threads, even videos!) on how to document a software project.

What I'm looking for are the best practices (even is subjective) on what is considered a good documentation: * How to comment your code? (ok this should be well known :) ) * How to document you architecture? high-level? low-level? * How to document your strategic decisions (two years ago we chose A instead of B because X and Y) * ...

Do you have any resources to share?

[badhombres]

I've always found that documentation is a skill on it's own. You need to learn how to say something efficiently while answering as many questions as you can. If it's too much people won't read it, if it's too little then it's not useful.

Also learn how to ask questions, you know your project inside and out, try to go to someones position of not knowing anything. I always find stuff that seems so simple at first but then later realize that most people wouldn't know it or connect the dots because they don't know the project.

Here are some resources I've looked at.

https://jacobian.org/writing/what-to-write/

http://ericholscher.com/blog/2014/feb/27/how-i-judge-documen...

https://www.braintreepayments.com/blog/api-where-to-begin/

http://warpspire.com/talks/documentation/

[imauld]

"Design the architecture, name the components, document the details." - Rob Pike

Good documentation requires there to be good code underneath it IMO. If your code is confusing and hard to follow your docs will be the same since they will have to break all of that down.

Some rules of thumb I follow when writing my docs:

- Document what it does not how it does it (exceptions possible here as sometimes how something happens is important but not always). The how will probably change over time. The what will likely stay the same.

- Doc strings n all public methods are written with a user in mind. If was using my lib in a Python shell and I didn't know what to do what would I want to see if I called `help(foo.func)`.

- Doc strings for "private" (Python doesn't really have private but components with leading underscores are meant to be left alone) are written with other contributors to the code base in mind. They will have some more reasoning to them as to the hows and whys since they may need to know how to interact with this component at a lower level than the public API.

- If you are using a dynamic language make sure you add type information for parameters and return values. Document what exceptions will be raised and what cases they will raised in.

- I like reading code more than docs so most of my documentation includes examples of how to use something. Not every piece of code lends it self well to this but if you can do it, do it.

- Tests are an outstanding form of documentation. I'll usually look at a packages tests before the docs to see how it works.

These are all very subjective of course. I've used packages that I thought had great docs and others thought they were terrible. Here's an example of some of the things I described here:

https://im-auld.github.io/httpbase

[croo]

Take a look at the documentation of zeromq [1]. This is one of the best documentations I've read so far. You may notice a simple pattern in the structure of that documentation that starts with describing a problem, then follow with an explanation and/or a solution with examples. This is a simple enough mantra to have and I personally following that every time I try to document or explain something.

Always start with a problem. Problems are interesting.

[1] http://zguide.zeromq.org/page:all

[fludlight]

This is a pretty good intro:

http://docs.writethedocs.org/guide/

[andymurd]

Just write. Stop procrastinating on HN, and type this:

    mkdir doc && $EDITOR doc/index.md

[interatx]

This doesn't seem to answer all the questions.

[rajacombinator]

Find of examples of what you consider to be well documented software, copy what they did.