Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
I would love to produce great quality documentation. I would use LaTeX, etc. to capture the high level. However, business folks see this activity as a waste of time, and so I do not get to work on it. –  Job Nov 17 '10 at 18:24
add comment

10 Answers

up vote 8 down vote accepted

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.

share|improve this answer
    
Great answer. Did you find it difficult to get a Wiki up and running? Edit: From a non-technical perspective. –  EricBoersma Nov 17 '10 at 16:32
1  
+1 I agree completely. The thing that makes Wikis so much superior is that they are typically less formal and incremental, which implies that it is okay to publish whatever you have time to write rather than saving up for a big update. It is more likely to get done because it is a less formidable task. –  JohnFx Nov 17 '10 at 16:37
    
No - I was there when it was set up at the last place and they bought into it right from the off. Here there was one up and running. My suggestion would be take a really hands off approach, let the structure evolve, no rules until they're absolutely needed other than the following: (1) it's got to be basically professional and (2) before you can talk to someone about something, it's got to be on the wiki - "if it's not on the wiki, it doesn't exist". –  Jon Hopkins Nov 17 '10 at 16:38
    
The practical implementaton of "it it's not on the wiki, it doesn't exist", is if you ask another developer to do something for you (say while you're on holiday) then the details go on the wiki, not in an e-mail. Ditto all those process change e-mails (X must be tagged in all bugs now), bug summaries and lessons learned and so on. If they don't appear on the wiki, the other developers are entitled to ignore them. After people get ignored a couple of times because they didn't do that they soon start. –  Jon Hopkins Nov 17 '10 at 16:44
add comment

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.

share|improve this answer
1  
And (if run regularly) are not outdated... –  Kleist Nov 17 '10 at 18:44
    
+1 I always read the tests first to get plenty information on how the library works –  user2567 Nov 17 '10 at 21:35
    
+1K unit tests equate to use-cases and requirements specifications, but they cannot be ignored and tolerate no typos! –  Steven A. Lowe Nov 17 '10 at 22:24
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
    
I use javadoc too (when writing Java, of course!) In-code doc is easy, and having a tool right in my IDE to pull it out is great. –  Michael K Nov 17 '10 at 16:44
    
Of course, similar tools are available for most other languages as well. –  Joonas Pulakka Nov 17 '10 at 16:47
add comment

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.

share|improve this answer
add comment

(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.

share|improve this answer
1  
I tend to agree with the premise of your post, but in this case I was looking for non-code examples. Certainly a restricting criteria, but useful for the purpose of the question. –  EricBoersma Nov 17 '10 at 21:14
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.