How do you document projects you work on?

Question

Where I work, I'm constantly doing development work. We're usually in a position where we're always busy doing development work with no time to write real maintainer documentation. I doubt my position is unique.

My question to everyone is, how do you/your development team handle documentation?

Do you document as you go? Do you write documentation at the end of the project? Is there a separate team of people who are solely responsible for gathering and writing documentation? Do you use inline documentation like Javadoc comments or .NET's XML comments?

What does everyone find to be the most effective, and how do you plan time to actually write it?

Answer 1

Commenting within class headers as development occurs using Doxygen. Then after project is done review design documents to confirm their accuracy.

Answer 2

We document as we go. Code reviews help in making sure code get's documented - and depending on your technology stack, there may be tools that help measure the level of documentation.

For Java we use JavaDoc, for Perl we use in-line POD with some JavaDoc style additions (parameters and types, return type and exceptions), for Ruby it's rdoc style and in our C and C++ code we used Doxygen.

My best experience has been that waiting until the end will result in things likely not being documented, and if they do, it's often of lower quality than if you've done it as you write and use the code - that second part has been especially valuable - as a developer creates a class, or library, they'll fill in a description of what they feel it is for and some examples of how to use it. As the library gets used though, I've found that the usefulness of the initial examples often turns out to be low since the original author didn't always see it the most clearly. Encouraging developers to update the documentation when they find that the have arrived at a library because they're using it has helped in the clarity of the API documentation immensely.

Answer 3

It all depends on what you code. As a general rule, I tend to write documentation before implementation whenever possible. For a command-line tool, writing the manpage is always a good start, for example.

I only use docstrings to document very narrow portions of code. Everything that relates to more than one function usually goes in a text file under version control (either a wiki or in the same source tree as the code).

There shouldn't be time planned to write documentation: documentation writing should be an integral part of coding. I don't consider code finished until it is properly commented and possibly documented outside code.

Answer 4

I find that if you document as you go, you're likely to realize when you're writing something that doesn't sound right, so you fix it in the code before it becomes an issue.

That said, it's far too easy for documentation to get out of synch with code.

Answer 5

Note, this is for .Net development...

We use XML comments in our code. The GhostDoc plug-in is very useful for this because it can quickly generate reasonable guesses at descriptions and documents parameters with a click or two. Sometimes you don't even need to edit it (although it's a good idea for more complex routines).

We use Subversion and require descriptive comments (particularly links/references to issues and bugs) for each commit. We're looking into scripting a bridge between SVN and our SharePoint issues and tasks list so that we can automatically document and cross-reference code changes. We used to do this with CVS and Mantis and SVN and Mantis.

Our primary project documentation is stored in a project/department SharePoint site where we also host our issue tracking lists, requirements list, discussions and archived e-mails, and a project Wiki where we maintain background details and "how-to" snippets.

We use a different SharePoint site for our software engineering standards, coding standards, and links to useful resources.

We have a few dedicated people who write our integration and acceptance tests and the user documentation.

That being said, our design and implementation documentation is never as complete or accessible as we would like it to be. SharePoint is a nice project documentation home, though. Particularly when we moved our requirements into a SharePoint list then wrote a mail-merge type "report" to format them back into a document to give to, and review with, the customer. You can do a lot with just Windows SharePoint services instead of a full SharePoint license.

At a previous job we used a Wiki (I can't remember which one) with a Wiki-To-Doc XSLT script that would build our user manual, our help file, and our context sensitive help directly from the Wiki (this was for a thick client project). That way, theoretically, we could easily maintain the documentation as we went and not have to reformat it and rewrite it into a help file/manual at the end.

Oh yeah, the one cardinal rule (which is just as hard as "document as you go") is "try to document things only once." If you try to document your design, the document your code with comments, then document your implementation, then write your user and maintenance documentation, there is little to no chance they will stay in sync. That doesn't mean there needs to be a single document or a single way to document things, just that you need to have a plan to bring it all together or make the documentation "discoverable" throughout the life of the project. Hence what I was saying above about building documents from SharePoint lists, creating documents from XML comments, tying your SVN commits to your issue and task system, etc.

Answer 6

no time to write real maintainer documentation

Do you have time to write unit tests? What about useful logging? Comments in the code?

These tasks are all part of doing development. Your schedule and time estimates should include the time required not only for writing the code, but also for testing it, documenting it, and everything else involved in producing an application.

So yes, document as you go. Have diagrams about how the application interacts with its dependencies and other systems. Include notes about design decisions, alternative approaches, and future plans. Be sure to produce operational docs as well - how to deploy your application, how to troubleshoot, etc.

Answer 7

IMO, you have to make a clear difference between:

• API documentation (dowygen, javadoc, ...)
• technical documentation
• public (for the client) documentation.

The last one is often mandatory, by contract, and will be done (eventually) ;)

The second one is done by making another developer (who did not develop the original code) add a new feature: the first coder then has a clear goal when he writes that documentation - make sure it has at least enough information to enable someone who has no prior experience with that code to quickly know where to start.

The first one should be done. Always. And yet it is not done as often as I would like (or as well as I would make them) ...

Answer 8

We don't document code, but we write specifications upfront.

Once you understand the concept it should be no problem to understand the code even without code review.

But we write comprehensive documentation for installation and operations, in particular how to monitor the applications and how to act under special conditions.

User documentation is usually written during the acceptance test by the users themselves in order to speak their language.