Documenting higher-level concepts

Question

I will be leaving my current project in a few days, and as part of securing my knowledge I have been asked to add comments to the code wherever I feel that can add value.

The problem I am running into now is that the comments I want to write are not really suitable as comments, because they do not pertain to a single entity in the code (a few lines, a function, a class or even a file), but they are more about how two or more entities interact with each other or about a feature whose implementation is spread over multiple entities.

So, how do you go about documenting the stuff that does not belong to a single entity but is important to know to understand the bigger picture?

And also: Where do you document it? In the source file or in an external document?

As an example, we have a client-server architecture in C (with the client and server both running on the same embedded device). To avoid flooding the server, the client has a mechanism to throttle the sending of similar requests to the server such that a request can only be sent if the previous one has been answered.

The innards of this mechanism are spread over multiple functions.

Where would you place the documentation of such a feature, especially if the file with the functionality also has some other, unrelated, functions?

Edit: Extended the question a bit.

Answer 1

You can probably utilise simple UML diagrams to highlight the high-level concepts.

Answer 2

Describe the system through tech articles which address certain scenarios, depict problem solving ways and so on.

Install a wiki and put the articles online so that the other team members can edit them later.

Answer 3

I've been using TiddlyWiki to gather some ideas that would not necessarily make a coherent text... This gets you a single HTML file that contains a Wiki that anyone can edit.

Compared to a real Wiki, this is much easier to setup, and it can be stored in your source tree so that it 'follows' the branches and the changes between them. On the other hand, it's not something that can be edited by several person simultaneously.

Answer 4

+1 for Wiki.

If it is a message passing system then I suggest generating sequence diagrams to show the interaction between the different components. I have used the following website to generate diagrams from simple text so no need to fiddle with any tools.

http://www.websequencediagrams.com/

One thing we have found useful is to ask the person leaving (you in this case) to come up with a quiz related to your area of expertise and then have a separate session to go over the questions and the answers.

HTH

Answer 5

I suggest to keep the code intact and describe your design in MS Word with referenes to source code and supporting UML diagrams. Don't spend you efforts on wiki - you don't have neither time nor incentive for real cross referenced documentation. The real power of wiki is semantic network built around some topic and writing wiki with one page is poor style.

Any documentation that is written after project is finished tends to be official statement rather than guidence for supporter/maintainer. This is similar to writing unit tests after the module is implemented. Although they are still useful but they are much less detailed then if you write tests first.

Design decisions have to be pronounced before you started implementing something. It may be simple note like "Ok guys, I have an idea, what do you think about it?" or formal proposal with UML diagrams and meetings. Whenever I start new task/component I try to announce what exactly I'm going to do. And the medium that I choose is not really important - it can be email, blog, wiki, JIRA... Of course design will change in later development but these documents will serve as draft for release documentation.