Documenting projects

Published on 23 June 2013.

Today’s thought is about documenting projects.

I think documenting projects is important. That doesn’t mean that I like to write a comment for every function I write. What does it mean?

When I look at a new program or library to use, I often start by reading the documentation. If a project lacks documentation, there is a high probability that I move on to the next unless the project seems really interesting and I can’t find an alternative. So high-level, big picture documentation is something that I value.

What is the best way to write such documentation? I find use cases or examples to be very effective. I want to use a program or library to perform a certain task. If that task or a similar task is described in an example, I can get started very quickly. Low-level details are easier to figure out by myself once I have the big picture.

Once a project has attracted my attention, and I believe that it will be useful to me, the next thing I look for is how to install it. That is another important thing to document. If I can’t quickly get it to run on my machine, there is also a high probability that I move on to the next project.

Site proudly generated by Hakyll.