I'm working on a large project and I would like to put together some technical documentation for other members of the team and for new programmers joining the project.
What sort of documentation should I have? Just /// code comments or some other file(s) explaining the architecture and class design?
I've never really done documentation except the occasional word doc to go with smaller apps, and I think this project is too large to doc in a single word file.
I have written - and benefited from - the following:
Architecture documents that explain either the system or an individual component as a whole. These are great for new hires to read to get the "big picture" on how your stuff works. Typically these contain high-level diagrams that explain how different parts of the system communicate with one another, along with an explanation of each component of the system, what its role is, etc.
Formal design documents; when writing these, each is prepared with a specific feature in mind, and goes through a formal review process. Although these do not always stay up-to-date years down the road, they give good insight into each individual feature. This documentation lists the formal requirements, data flow diagrams, class diagrams, and details the modifications to the system by technical area (database, middleware, user interface, etc). It may be difficult (if not impossible) to write these after-the-fact, though. Your best bet with these documents is to include them as part of your development process, if it makes sense for your team.
Comments in the code that can be transformed into API documentation, such as JavaDoc. These are good to have for reference, to explain things at a much lower level.
You may not be the one preparing these, but they can be useful as well:
Requirements documents may also be helpful depending on how well they are written, although honestly I have found other forms of documentation more useful for understanding how the system works. Requirements documents are better for driving your design efforts.
For newbies you should also briefly document your source code structure, the check-in/out processes, where to find tools, etc. Then, when a new person comes on board, have them update the doc and add whatever they feel was missing.
I would strongly recommend you to go through doxygen and edit your source files appropriately. Then run doxygen and it'd generate enough technical documentation like class hierarchy etc.
In fact make doxygen a part of the build process, and keep following the commenting convention as you go.
Just the architecture and class design alone is not good enough for big projects. Here's the minimum:
It depends who do you write the documentation for. If you write it for mates programmers, it should probably be documentation in the code, let them be commentaries or more formal doxygen-like documentation. On the other hand, if your manager or customer wants to know technical details, a list of classes and what they do won't tell them much. So in that case you might want to consider having diagrams, as well as high-level description. For end-users, you probably want some FAQ, user manual and tool tips (in case of GUI application).
In the company I work, we have no customers, and no user manuals whatsoever. But we do have both high-level documentation with rationale, goals, abstract architecture etc., we have documents with network topology, latency metrics etc. And, of course, we document the code (using Doxygen) and trips&tricks in our corporate Wiki. Aside from that, we have JIRA where you can find who is working on what, what has been done and what actions performed.
Following are the documents I will recommend. Even if you put the comments in the code, I feel that you should know something about what the code is doing before going to code.
1) Use case documents/Detailed Requirements
2) Design Document
3) Unit test case documents
4) Integration test documents
