18

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.

Improve this question
3
  • 2
    //Documentation -> see code. :P
    – Darknight
    Dec 23, 2010 at 13:44
  • 1
    @Darknight: You read my mind :-) I don't read documentation as long as there is no bug reported and I assume code does what it has to do. Documentation is often outdated and does not reflect what is really going on in the code. So I read code. And, what is strange, I read C++ faster and understand it better than English :-)
    – user11408
    Dec 23, 2010 at 13:49
  • 1
    What is this "Technical Documentation" thing you're mentioning? Is it a kind of pasta?
    – dr Hannibal Lecter
    Dec 23, 2010 at 14:17

5 Answers 5

Reset to default
17

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:

  • User Manuals, Guides, etc - For a new hire, these can be helpful to get a different perspective on how the actual product is indented to be used by your customers.
  • Test plans - Very tedious to read and more "interactive documentation", but sometimes the best way for a new hire to learn is to run through the test cases on an actual system.

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.

Improve this answer
5
  • What sort of software do you use for your formal design documents?
    – Rachel
    Dec 23, 2010 at 15:06
  • I use Word to write the documents, and Visio to prepare any diagrams for them. You could use other software if you want, these tools just happen to work the best for me, and are (mostly) accepted by the team.
    – Justin Ethier
    Dec 23, 2010 at 15:20
  • Ok thanks. That's mostly what I use but I was wondering if there was some other standardized software for technical documentation
    – Rachel
    Dec 23, 2010 at 17:10
  • From my experience it is more about using standard templates, document structure, etc than about data formats or software.
    – Justin Ethier
    Dec 23, 2010 at 17:48
  • +1 for Architecture documents is very essential for large project. Since they'll small pieces are scattering around, which make it very hard (if not impossible) to understand solely from code for new comers.
    – Zekta Chan
    Jan 2, 2011 at 18:37
3

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.

Improve this answer
2

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:

  1. Please document global variables. No exceptions.
  2. If a function is modifying anything other than its inputs, please specify the same.
  3. Any non-trivial stuff that some routine is doing. Particularly, if you are implementing some complex algorithm, include a reference to that algorithm url or paper.
  4. Known hacks that you put in and had promised yourself to fix it over the weekend.
Improve this answer
2
  • Having doxygen/javadoc/your language's doc tool here in the build process means I can quickly and easily reference another class or method online or in my IDE, and that saves me time as a programmer.
    – justkt
    Dec 23, 2010 at 15:14
  • How much time would you estimate it takes to setup, learn, and implement doxygen?
    – Rachel
    Dec 23, 2010 at 18:36
0

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.

Improve this answer
2
  • It's for other programmers. We do have some high-level documentation outlining the overall program, which is what the managers see if they request it, and we plan on doing user documentation last.
    – Rachel
    Dec 23, 2010 at 13:48
  • 1
    @Rachel: For programmers, it also depends on programmers qualification. Some just barely can read others code. That is bad, so for those people you to go over the code and put comments like "This function prints hello" above the "printHello ()" function. But good programmers can actually understand it w/o comments. So put description only when you feel it is necessary. For example, in some complex algorithm implementation. That's about it :)
    – user11408
    Dec 23, 2010 at 13:52
0

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

Improve this answer

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