
Ask HN: How to document your *project* - dvd0101
Hi, I&#x27;m looking for online resources of any kind (articles, blogs, threads, even videos!) on how to document a software project.<p>What I&#x27;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)
* ...<p>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/](https://jacobian.org/writing/what-to-write/)

[http://ericholscher.com/blog/2014/feb/27/how-i-judge-
documen...](http://ericholscher.com/blog/2014/feb/27/how-i-judge-
documentation-quality/)

[https://www.braintreepayments.com/blog/api-where-to-
begin/](https://www.braintreepayments.com/blog/api-where-to-begin/)

[http://warpspire.com/talks/documentation/](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](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](http://zguide.zeromq.org/page:all)

------
fludlight
This is a pretty good intro:

[http://docs.writethedocs.org/guide/](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.

