

Ask HN: What are the best practices for documentation? - SatyajitSarangi

I've read contradicting essays of what the documentation must look like. Some suggest more documentation is good, when you hire a new chap. Some suggest less documentation is always better, as your code should be explanatory enough. If not, you've hired the wrong coder or written bad code.&#60;p&#62;So, how should one document:-
1. Code
2. DB design(Is just an ER diagram enough?)
3. API end points.&#60;p&#62;I'm the only one involved in coding and setting the "standards" when it comes to these things, so was wondering what do others follow here.
======
tjr
I think the answer has to be, "it depends on the project".

I've read numerous gripes against commenting code, because it's possible to
change the code but not the comment, rendering the comment inaccurate. I
reckon that's true, and it's certainly a reason to be as conservative as
possible in commenting code. But how conservative is that? None at all?

I have at sundry times worked on a codebase that simulates a fairly complex
avionics subsystem. It's a hundred subprojects of C++ code, almost entirely
undocumented. I imagine it all makes sense to the original author, and it
might make sense to someone intimately familiar with every facet of the
avionics subsystem that it simulates.

The function names _look_ self-documenting; the variable names _look_ self-
documenting. But the problem is, you'd have to read _and thoroughly
understand_ something like a thousand pages of dry ARINC specifications before
these self-documenting function names would reveal themselves for what they
are.

I have a hard time believing that the best way to document this software
project is "not at all".

In general, I personally like to draft a design document up front that
explains the intentions of the project and rationale for choices made, and for
why the project needs to exist in the first place. Some good hints at:

<http://philip.greenspun.com/software/design-review>

The larger and more complicated the project, the more in-depth the design
documentation should be. Even for quick weekend web app hacks, spending a
half-hour drafting a design document can be beneficial.

