The Importance of Documentation

Have you ever assembled IKEA furniture? They have the best little picture diagrams of how to attach the leg to the table. It makes assembling a piece of furniture with 50+ pieces a snap. On the other hand, if you don’t read the documentation and think that you got it under control, you can assemble the damn thing almost perfectly except for the two almost identical looking pieces and then have to take it apart and do it again. However, when you get to software projects, after documentation and reasoning is neglected you end up with something like this from coding-horror.

Anyone who’s had to dive into a several year old codebase ends up wondering, how the hell did this happen? Naturally, there is a bunch of reasoning that made complete and obvious sense at the time due to business reasons, time constraints, or other external conditions. That’s fine. But there should be a README outlining why it’s doing that. Same thing goes with open source projects, if I can’t figure out how to use your project, I’ll either roll my own or find another project.

This is what I want from documentation:

1. If you have an API, tell me the common use cases and what each function does.

   • Look at firebase examples.
   • Or AWS tutorials and the api.

2. Tell me the common tuning/failure points/limitations.

   • Wouldn’t it be nice if in the Apache setup documentation they told you about MaxClients, ServerLimit, KeepAlive, etc. if you have high-traffic?
   • Do you know your application’s resource usage and growth? If so, write it down.
   • Would it be nice to know the limitations before using? Here’s some for parse

3. Tell me exactly all the end-points the code may or may not connect to.

   • If you’re storing something in datastore A and something else in datastore B and then merging them, write it down.
   • If you have external partners, those connections and what is being done should be apparent.

4. Give me some reasoning about the design.

   • Is the project meant for a specific use case?
   • Is there a reason why one tradeoff was chosen over another?

5. Give me the code with a Vagrantfile.

   • The last thing I want to do is figure out how to deploy and run the code.

Projects fail because of bad documentation. Features are unused because of bad documentation. Code is great, but code with documentation is better.

tl;dr - write examples, reasons, common optimizations/failures, and endpoints