How do you document your application?

Question

I never know how to document a system in a way that other developers will find it easy to use and/or maintain it. Documentating the source code is good and required for that, but I don't think it is enough to give a good overview of the application itself.

Java seems to keep most of its documentation in the source code, which describes only basic usage of certain classes - creating a DecimalFormat object for using a comma as the decimal separator is non-trivial if you stik to the (generally quite verbose) API documentation only (as far as I understood from their documentation it involves the DecimalFormatSymbols and Locale classes, but the point is: I can't tell for sure without further information). The missing parts are then tried to be covered by separate Java tutorials, which mostly describe distinct special use cases of their library.

The Ogre3d graphics engine, on the other hand, created special pages for the general description of their application, which is available as the ogre manual and they try to explain the wholeness of their engine there.

I know, the scope of the libraries are not the same here, and I'm not bashing Java, but thought it would be an appropriote comparison of documentation philosophies.

We recently started putting all our documentation into the source code in our company, which made me wonder: How do others document their applications and how does it work out for them (or more importatly: for other developers joining their project)?

EDIT

I guess I need to clarify a bit: When a project grows beyond a certain (code-/team-) size it gets hard for other developers to join it. I know that code documentation is very important for them to understand the code, but I don't think it is sufficient to get started working on the project. Either someone else has to give him a tutorial (explaining why things look the way they do), or it needs to be documented somewhere.

So the actual question is: What documentation do you provide to new developers and how useful is it to them? Do they read the 200-Page system documentation? Do they dive into the code first? How many and what kind of questions do they ask after reading them?

I'm not after the reactions of your colleagues, but the efficiency of your documentation process (just mentioning the reactions as an indicator).

Answer 1

I try to keep documentation in the source code. Since I work in C# i use the /// system for documentation. SandCastle can later be used to generate documentation from the comments. I think a wiki is a good idea for high level documentation too.

Answer 2

we try to maintain the Documentation inside the code. We use Javadoc for that.

Doxygen is a nice tool for generating class diagrams directly from the source code.

Sometimes, depending the platform we are using, we generate ER diagramms via reverse eng. There are lot of tools for doing this.

This is the documentation the client is going to get.

Some other documentation like installation procedures, how to backup the system, how to make a new deployment, etc is documented in a Wiki system.

Answer 3

I will have to agree with JamesC78. When I program in Java, I do the usual comments and JavaDocs for the developers. But then I also update a Wiki with some lower level documentation like how to run the program, what to look for, what database tables are used, what it's doing, etc.

Answer 4

I read and re-read that question like 3 times to determine if you mean document the USE of your product vs documenting how to develop your product vs commenting, and in the end, I still cant tell which you are after! ;)

Now that I work for myself, I have to admit I am pretty terrible at it. I comment for my audience (me) mostly in the form of reminders or explanations to myself. I have a somewhat terrible memory at times, so this is a useful exercise. I don't know how much other people will get from my documentation, but it works for me. I use the built in tools from Visual Studio ( /// ) which allows for later automatic documentation to be made, similar to javadoc or oxygen. I also make heavy use of //TODO:

As to, how do I document how to use my products, simple, I don't. I firmly believe that developers should never document their products usage, as as the developer, you will use your product in a much different way than end users will. At my last job, documentation was generally handed off to a power user or QA within the company, with that person having access to the dev team should any questions arise. Point blank, most developers really aren't very good at communicating to non-technical users, although there are of course exceptions.

Otherwise, I did get in the habit of maintaining a "Here is how to do my job" manual, that I would update every few months if things got slow. In my case it was just a sprawling oneNote document. But when I got hurt and was off for a while, it proved invaluable and minimalized the number of calls I received. Since, I had all developers keep a similar journal, with varying levels of success. That said, this goes directly against job security, so I hope you feel secure in your position.

Answer 5

Firstly, and this seem obvious but not many people seem to follow it well- write self-documenting code.

Secondly refactor the code to make it easier to read- the classic example of this is the Extract Method refactoring.

Thirdly and this seems obvious- if you do write JavaDoc style comments, don't go overboard. In a previous company one of my coworkers looked at someone else's code which was heavily documented, only to find the documentation was the exact opposite of what the code was doing. If you are going to heavily document code then it is important to make sure it "lives" with the code.

All too often people document the code, change it and then don't update the documentation. If I stumble across .NET code that is badly documented I usually use Reflector to get a better understand of what is going on.

Finally people forget that unit tests can also act as documentation.

Answer 6

If this were a Python project I would suggest doctest.

For example, here's a small doctest that describes how to use a simple advisory file locking package.

There are at least two doctest-like system for Java: JDoctest and doctestj