Software Artisan

I’ve been using this blog as a way to talk about my adventures in programming, but as of late I sound like a broken record. I don’t have time to explore new things like I used to, and right now I’m in the process of pounding out code. It’s not active design, nor am I in control of the project any more. Times cycle, and I may be in that position again—even soon. However, I have a creative outlet with my photography. There’s different things you can do in the darkroom, new experiments to try with developing, etc.

I’m going to focus on my hobby, where I have most of my fun. All the old articles are still here, and won’t be going anywhere. I did want to give fair warning, knowing I’ll lose some of my audience. You may enjoy it if you stick around, so let’s all have fun and enjoy ourselves.

I‘m going to be as blatantly honest as I know how to be. Writing good documentation is hard . This post is inspired by FransBouma who in turn responded to Jeremy D. Miller. At the center of contention is the role of documentation, and whether it is kosher to assert that a TDD unit test counts as documentation. Now, my focus isn‘t adding fuel to the fire, but rather looking at the bigger problem.

Let‘s consider first and foremost that everyone seems to agree that there should be some level of documentation. What’s at stake is not whether we have documentation but rather its form and content. We also are aware that instinctively, we software engineers stop managing traditional word processing documents at the first opportunity. We do this because we know that it really doesn‘t have any immediate usefulness, and thinking about what the maintainers will have to face when the boss is breathing down your neck is the last thing on your mind.

Let‘s recognize the contributions to documentation that agile processes and TDD have brought to the table. By recognizing that many documents only have ephemeral (temporary) value, we don‘t have to maintain them for posterity. Also by realizing that documentation is painful to write, they try to instill a practice that kills two birds with one stone: some documentation is better than no documentation, and documentation that can pull double duty and check your code has immediate payoff. Granted, traditional unit tests are written in the language of the code you are testing. It requires a certain a priori (pre-known) knowledge to understand the tests. You have to know the language that the tests are written in, which is usually a safe bet because we are testing in the same language we are writing. You can argue till you are blue in the face about whether or not you can consider it a form of documentation, but it does provide the assertions that the working code must obey. That is, at the very least, a useful amount of information that works in our advantage.

So what kind of documentation is useful? I mean it‘s all fun to argue about the virtues of documentation when we haven‘t even begun to discuss what makes a good document. Have you ever seen a 17 volume specification with reams of paper having diagrams, text, and what not? Something like that is utterly useless. The last time I was asked to review something like that (we all took sections), we gave our input, and with each iteration we found that the documentation was never changed to reflect our concerns from the last time. What does this tell you about the purpose of a 17 volume design spec? It‘s only purpose is to throw so much crap at the client they will simply sign on the dotted line instead of actually validate that you did what you said you were going to do. That is not useful to anyone. Not to product maintainers, not to people writing the software, and definitely not to nontechnical people.

Here is a short list of guidelines for good technical documentation:

• It should be focused on one thing. Don‘t try to use the same document to tell people how the software is designed, how to perform system administration, and how the process is done. These are all separate documents with separate audiences.
• If you have to think about it hard, you have to write it down. At the very least write down your final decision. Typically, these are the things that will catch people by surprise.
• If it‘s a surprise to you, it will be a surprise to someone else. How to write a Google Nest is a perfect example of what I mean.
• How Tos are better than “what it is”. Maintainers need to know how to do something, not what its structure is.

There is some value to writing down the pros and cons as to why you chose a specific solution over another, but at the end of the day, most people don‘t really care. Sure there is some academic value to it, but a decision usually is the best of what was known to be possible at the time. Times change, and so does what solutions are available. It could be that you abandoned a design path because the underlying technology hadn‘t caught up to your vision yet. For day to day tasks, the bullets I listed above are more useful.

Now, what form should documentation take? Should we break out our word processor and create a templated document? Maybe, maybe not. The key to evolving good documentation is to make it easy to do so. If you can incorporate the documentation, or key parts of the documentation, into the code, then you are effectively lowering the barrier to have developers maintain it. Of course, there is nothing wrong with using a good project wiki. I‘ve found that to be the best way to get ideas and information down, and move on. It isn‘t formal, and it is designed to be easily linked. That means it is easier to maintain. Of course, passing the wiki on to the maintainers is the next challenge — but there are solutions for that already.

Technorati Tags: documentation, design