What kind of code overview documentation do you write?

Question

As suggested, I have closed the question posed here and have broken it up into separate questions regarding code documentation to be posed throughout the day.

---

This is the final question in the series.

• The first part: How do you document your methods?
• The second part: Are tests valid documentation?

This question has to do with what documentation overview do you provide of your system.

You've doc-commented your API, you've written the unit tests, now what kind of documentation do you provide to pull it all together? Is there only documentation from the point of view of the user or do you make an extra effort to provide maintanance programmers with an overview of the system's logic and control flow? Do you discuss why your program is structured the way it is and how far down that rabbit hole do you go?

Should this overview documentation be provided in a single document or broken down by the system's major components? Keeping in mind that the target audience are other programmers what is appropriate for length and tone? Do you mandate what concepts the programmer should be familiar with or is that being to bossy?

Do you write this documentation in a big bang at the end or as you go? If you do it as you go then how do you handle keeping it in sync with design changes?

What do you do for this important step and what do you like to see has been done when picking up someone else's project?

Answer 1

Personally, I think this is the most overlooked part of most projects. I am far from blameless in this as by the time I reach the end of a project I am sick and tired of the thing and don't want to see it again much less spend time discussing my design decisions which I've usually decided by then were all stupid to begin with.

I will usually include a README document written at the end of the project spending a few pages discussing how stuff works but rarely why.

What I like to see is a programmer-oriented tutorial on the code. This would I imagine be a few pages on each library, showing how to use it and maybe even giving some integration examples of how the puzzle pieces fit together. I think it is then necessary to provide an overview of how those components work together too.

Ideally, I think there should be a spectrum with the more technical writing being on the level of doc comments and the less technical being on the level of describing the whole system. An html or similar hyperlinked document is then always superior to plain text.

Answer 2

Do you mandate what concepts the programmer should be familiar with?

Yes.

By far the best examples are documented example applications, especially for frameworks and large scale systems. Better yet, a progression of applications. I.e., one for which libraries you need, one simple connect and hello world equivalent, and on from there. Explain the gotchas and "this isn't what you expect" parts. Combine this with some clean flow and logic diagrams, and explanation of the major parts.

Answer 3

Well for Methods I like to put my documentation first. So for instance

* Created By: peregrine Created on: 09/15/2008

Name: DoAwesomeThingWithX

Variables needed: Int Returns: String Description: Does something awesome with x and returns a string REVISIONS: Jason 09/15/2008 Added slightly less awesome functionality.

*/ Then you have revisions and etc etc. This isn't a very strong approach but I find it helps you make sure you understand why your doing the method and to remind you or others why you created it. Sure you can most likely remove the variables needed and returns fields as they are useless when the user looks at the function name.

And for number 2 tests to me are worlds more useful then any sort of documentation. Not only can the user updating the code test his fix immediately with valid tested data they can see what type of stuff the code was intended for. I love when people put test cases on top, especially for Stored Procedures. I love em.

Answer 4

The Mythical Man-Month, that famous book by Fred Brooks, has an essay on the types of documentation that are vital to managers, professors, anyone working on a software project.

Answer 5

I create a wiki page that covers the overall architecture of the system, the functional components, and a general overview.

Inside of the project directory I create a dev/ subdirectory where I will create text files with things such as database schemas, examples of code that I've found searching online that I might modify to include in the project but I want to keep a note of the original context somewhere, and perhaps text files with to do lists, reminders, and other things that are useful to myself or the other developers.

Then I document the code inline as I write it. And when it's finished or at least at a point release I go back to the wiki page and update it to make sure that what is explained there actually bares some resemblance to what was produced.

I don't do a lot of documenting class hierarchies or function definitions in the wiki because I find that they can change over time as we develop and the wiki becomes out of date. Of course this is less of a problem for me since my projects tend to have a small development team. For a larger project the software architecture would have to be more locked in stone beforehand with that sort of thing really defined. But for our software development methodology we don't do it that way.

I like having the dev/ notes in the actual project directory because it's quicker to refer to them than having them in the wiki and if anyone on the wiki is that interested in the development notes they can click over to the Subversion web interface to look at them.

Answer 6

There should be a specification document that has the necessary details on what was coded and why it was coded. If it is a large piece of code, e.g. thousands of lines of code or more, then it may be worthwhile having separate technical documents giving an overview of the system but I find this to be rarely written down though it is usually in someone's head in any organization. Rabbit holes can be like black holes in terms of how far do you want to go in terms of complexity in time and space as well as the concepts of load and parallelism, i.e. does the code optimally run within a quad-socket quad-core setup or is it better on a single core workstation setup.

The specification I mentioned before should be done for each project and thus there may be multiple documents for one system if it is done in phases. I tend to find that short and to the point documentation is better than lots of fluff that doesn't help me to use a component or replace a piece of code.

Usually that specification gets reworked over the course of the project so that it is up to date with any changes that occured as I went along. The sync is simply coming from a developer having the spec on one side and the code on another and seeing that they match up, i.e. that the code does what the spec says and not something else.

I don't usually consider this to be an important step as generally it will be replaced in a few years with something better that comes along, e.g. ISAPI extensions got replaced with ASP that got replaced with ASP.Net 1.0 that got replaced with ASP.Net 2.0 and so on... Generally, I like to be able to see the big picture and then drill down as needed since I'm usually looking at code for only a few reasons: 1) Fix a bug that was found with the code. 2) Implement some enhancement or new feature that someone has requested. 3) Replace the existing system by figuring out the strengths and weaknesses of the existing system.

Why else does one look under the hood is another way of viewing this, IMO?

JB

Answer 7

Depending a bit on who you write the documentation for, different levels of "tech" is needed.

I would want the project to be documented as I would like it be as if I was a newcommer to the project. I needs to be meaningful. As an example of a medium sized 6-10 people 3-4 months peoject:

On the top I would start out with a SAD (Software Architecture Document) describing the major flow, concepts and structure of the app/project. Describing the (in high level) the inner workings and external dependencies.

I would continue with a more detaild specification of the parts of the project i.e. web client, win client, differenct WCF services etc. Including specific configuration made for theese parts, for different environments, ie production connectionstrings, WCF service detaisl, external contracts etc.

On the far end of this I would make sure that methods, classes etc, are properly commented to be able to generate documentation from this, via sandcastle or any other tool.

I would assume that ceratin skills would be needed to read the different parts of the doc.

And I would (well try atleast) to make sure that the docs should be worked on before delivery and be a part of the whole delivery.

:)

//W