Documentation is an extension of the engineering process not an afterthought
or a separate process. When I say documentation, I am referring to the text you
produce that gives an overview of how a project was done (architected) and, in
some cases, how to go about using something. I am not talking about inline
documentation like code comments. When you document a project you are seeking
to answer two questions:
- Do I understand what I just did enough to explain it?
- Upon review, can I improve what I just did?
The first question challenges you to actually explain what you just did. If
you were explaining a feature you wrote you would talk about how all the moving
parts fit together. To put it a little more concretely you explain how certain
classes/objects interact with other classes/objects, how you went about
segregating your work, what design patterns you did, how data flows from one
form to another. This is what people care about, because here you describe how
to actually use what you did. I am a huge fan of providing concrete, full code
examples of how something works. If you want to know how something works, the
best way to learn is to look at the code. This is extremely easy when the
person who wrote it provides a concise detailed walkthrough. A good example of
this would be the JDeveloper
ADF tutorial docs. Clear incremental examples walking through how to do
something complicated. If you can answer this question you prove to yourself
you fully understand what you just did. If you cannot answer this question you
will pay for it in the future, either in your inability to help others use what
you have written or the difficulty you face fixing a bug/adding a feature. Use
documentation to ensure you know what you are doing.
The second question is a byproduct of the first. While working through what
you just did you are also evaluating how well you actually did something. This
is akin to editing a completed work. I can only speak of my own experience, but
I have two working modes: producing and editing. When I produce I have a
limited view as I seek to solve small discrete problems one at a time. How do I
process this bean, where can I get this data, what SQL command returns the
proper set of data. It is only when I pull back out to editing mode that I can
take a broad view and see how my work integrates into other pieces. Why have I
not condensed all these similar business class function into one call, why did
I use a array in this data structure when a hash map offers a quicker lookup
time. When you are immersed in work it can be very easy to lose the larger
picture of what you are accomplishing. Only by reviewing what you have done can
you pull back and evaluate your creation.
This philosophy does not just apply to code. One of the guiding principles
of this blog is a venue for me to document my past project thoughts, like I
have done with my
helmet thus
far. I have found that the mere act of organizing the fractured thoughts into
ordered structured sentences can I better understand what I just did. It allows
me to understand the process I followed and determine ways I can improve it.
And that is the key to why I love documentation. Documentation is self directed
learning. This is your craft, it is worthless to practice a craft without the
desire for constant improvement. Use documentation as a means towards
constantly improving your craft.
For a more detailed, programmer centered overview, check out Yevgeniy
Brikman’s post on the subject.