What's the best documentation you produce and why?

Question

I think it's safe to assume that for most programmers, producing documentation is not as fun as actually coding. I think it's also safe to assume that most good programmers recognize the need for useful documentation, and the code that they write is not an exception by any stretch of the imagination.

So, I'd like to know: what's the best documentation you produce (and source code doesn't count). Answer can be anything from comments to unit tests.

The bigger question is why is that the best documentation you produce?

Answer 1

Our Wiki.

Because people actually use it and update it.

I think the nature of a Wiki lends itself to the way developers want to work which is just get the facts down and move on.

It's quick and easy, searching makes it simple to find what you're looking for which minimises the chance of duplication (and the subsequent "so which is right") and you need minimal technical skill to read or change stuff (as opposed to, say, tests).

Versioning is automatic, formatting is basic but effective which means the content tends to be prioritised over prettiness, and there's no pressure to have cover pages, change tables, summaries and so on all of which add work for little benefit. Because it doesn't have a specific structure, people just worry about putting down what's important, not what fits.

That's all my guess as to why it gets used but as a development manager the main thing I like is that it does get used and remains broadly up to date.

Answer 2

Well written tests. They describe what the code should do, and demonstrate that it works.

Since they are automatically run with every build, they are never out of date.

Answer 3

One of my pets peeves is the absent-or-afterthought nature of the documentation that goes along with virtually all open source software. While I think that it is great that other engineers release their code so that I can avoid reinventing the wheel, it is teeth-grindingly frustrating to find the code accompanied by nothing but a README file with little or no usage examples. Yes, I can read the source code, but code examples and some thoughts about the code strengths and liabilities would make all the difference in the world.

So, when I ventured into making my own projects open-source, I didn't release the code until I had written thorough documentation including extensive code samples, a step-by-step implementation guide and a real API reference. I did it in TiddlyWiki, a self-contained Wiki in a single HTML file, and I even used tags and built an index.

It was a lot of work, and it was not the kind of work that I really enjoy (coding), but it seemed irresponsible not to include truly useful documentation, and in the end, I did it because I was proud of the project. I wanted it to be of the greatest possible use to my peers.

Answer 4

Does Javadoc count? I think my API documentation is reasonably well made and maintained. Why? Because it's as integrated with the coding process as it can be, and its structure and notation is well enough standardized. No need to waste brain cells on thinking how to actually realize the documentation, or link it with the code, or version it, because all this just happens by itself.

Answer 5

(and source code doesn't count)

On the contrary, production code is the only truly accurate documentation you have. It describes exactly what your program does. Everything else: design documents, diagrams, code comments... can be misleading.

That's not to say there isn't value in all of those things. There is a great deal of value in many of them. But they all suffer the same problem. They are extrapolations of what the code actually does. As such, they will always be prone to inaccuracy.

Even unit tests are not immune to this. A unit test that isn't run can quickly become out of sync with the production code its supposed to test. And entire books have been written on how to write good tests. Which implies that it is just as easy to write bad ones.

That is why there is such a focus on clear, readable code in Agile methodologies. Knuth refers to it as literate programming. Writing code so others can read it and not just the compiler. Everything else just points to the code.

Answer 6

The documentation I write when I know someone else is going to have to take over my code. After an initial draft, I sit down with them and the document and go over the code. The document gets updated based on this review.

If the new person does the same for the third developer, it's probably pretty thorough. Then again, most 3rd versions are.

Answer 7

In one of my previous jobs before I left, one of my tasks was to help with this document that contained various tidbits about the code base, which was a mix of VBScript, JScript, and C/C++ for the COM parts in addition to various mark-up languages as this was for a dot-com after all. I believe it was nearly a dozen pages when I left and contained most of what I had learned in the ~9 or so months that I had been working there. This is the best I've produced because of how it is the closest I've come to a good brain dump of all the things that were in my head in working with most of this code. The leaving was more of a known issue when I started so in a sense it wasn't a shocking thing and it was kind of fun to try to spill the contents of my brain into a Word doc.

Answer 8

I use in code comments. I write them as I code, and comment each block explaining the process, not the specifics of how the code runs (no //set x = y comments!). I also use javadoc when writing Java code so that anyone using the code in our IDE has an instant rough guide to how to use my code.

For high level documentation (class structure, framework and installation instructions) I use our company wiki. That put all the information out in one place, rather than trying to distribute Word documents all over the place.

Answer 9

Good Requirements Documents

Developers come from all backgrounds, but a well written requirements specification can fill in their knowledge gaps and clearly explain the business and the objective of the user. You may not think a developer should be writing requirements, but if you can find a developer that is also a good communicator and good writer, you essentially have a business analyst that understands the complexities of software development, which is better than having a business analyst that doesn't understand the real complexity in software development (and there are a lot of those running around).

Why?

Karl Weigers once wrote that if you miss the requirements then it doesn't matter how well you execute the rest of the project, you are at increased risk for failure (and that's putting it a lot more mildly than he did). A good requirements specification doesn't have to be monolithic (although if the cost of failure is loss of life, then perhaps it might have to be) and a good one will get everyone, not just programmers, but also analysts, managers, project managers, subject matter experts, and end users on the same page.

Experienced developers know that the synergy of good domain knowledge, programming skill, and communication is important to successful software projects. A requirements document (on paper, wiki, or any medium) is a good part of that, not only for the beginning of the project, but also for life after go-live.

Answer 10

Any documentation written in natural language is susceptible to ambiguity. Code that is neatly written and well commented can reduce the ambiguity totally or almost totally. So, it should be a combination of code with comments and the specs that were used to write the code.