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.
–
What is Rickard working on and thinking about right now?
Every month I write a newsletter about just that. You will get updates about my current projects and thoughts about programming, and also get a chance to hit reply and interact with me. Subscribe to it below.