OSDev.org

Since my kernel's code has been non-volatile for a while now, I've decided to start writing some real documentation for it. The documentation will be focused on the internal structure of the kernel, so anyone who understands enough to do osdevving could read it, along with code comments, and be able to modify the code - a sort of "hacker's guide". The external interface (i.e. system call) documentation is straightforward enough, and is more like a manual.

The problem is, I've never written any real technical documentation, and I don't know the best way to structure it. Earlier, I tried to document all of the interface functions to the different kernel subsystems individually, but that took a lot of space, didn't give a very good picture of how things actually worked, and was totally redundant next to the code comments. I also tried writing a sort of "overview" for each subsystem, but things were so interdependent that it was hard to explain things in any specific order. In other words, I got some nasty circular dependencies.

Does anyone have tips for structuring/writing good internal technical documentation? Not only for my circumstances, but also in general - this seems to be a very under-discussed topic on the forums .

I try to adhere to UML when possible then most of the documentation comes for free during the process i.e. gather requirements, derive classes/modules/components, construct class/sequence diagrams & use cases, then finally write code. By the time you begin writing code following UML the app and docs are about 50% complete and basically just need the blanks filled in. Rational Rose is/was the best tool on the market for a long time until IBM ruined it. It was also way to expensive for hobby or home use but did an excellent job of keeping documentation on various components and their interaction.

I've never used UML before - I guess I'll try it out. But I don't have a problem designing or coding, and it's not like UML will literally write documentation for you, even if it gives you some nice diagrams. A picture is worth a thousand words, but hardly any set of a thousand words can be accurately described by pictures.

I use a mix of generous inline comments, and a .doc file in each directory, explaining what the module in the directory does, and how it should be interacted with by the rest of the kernel (for my OSDev project; At work there's a different system in place).

What kind of documentation are you looking for? I find class diagrams, state charts, activity diagrams and interaction diagrams adequate in most cases. Other people want paragraphs of text.

As for UML, it is more than just diagrams, it's an entire design methodology. It basically begins with an abstract list of requirements and ends with a fully documented project ~before~ coding. What made Rational Rose great (among other things) was it was the reverse engineering. If you already have the code it will generate the UML documentation based upon it. It also forward engineers the code based on the diagrams so you have a round trip and reiterative design, development and documentation process.

Whether you do PDF files with lots of UML diagrams in them or just a couple of plain .txt files doesn't matter, as long as you documented all of the following in an easy-to-find way:

• What is being done?
• Why is it being done?
• Where is it being done?
• How is it being done?

For me, I structure docs like this, usually:

System documentation / manuals tell the what (on a high level), and the why. (Motivation, background information, usage, glossary if necessary, that kind of stuff.)

Architecture documentation tell the what and where. (Which classes and files belong to which module, how do they interact, which algorithms are used.)

Source comments tell the what and why (on a low level). What does the source do, on a slightly abstracted level (so you can better skim the code to the relevant location). Why is the source written this way, if it's not quite obvious.

The source itself documents the how. Only the source can, so make it readable.

And yes, documentation carries redundant information. Think of the redundancy as a parity bit. If it doesn't match, there's a chance something is wrong. If you don't have the parity bit (redundant information), finding the location of a problem can become a quite difficult endeavour.

I would recommend to look at doxygen. It is very easy to use and got a lot of nice futures, especially when you also use Graphviz which gives you nice charts about how each file is included to each other.

Doxygen analyses your code and creates from this information an HTML page(or latex, pdf, plain txt etc.). In addition you can give him more information using special comments. With all this he can creates an documentation with assignment (for example: which function uses which functions and where they are located), information on the specific part, warnings and a lot of other things.

With this and a proper source annotation (which you should always have!) you can build a good documentation, without a lot of work. Here is a little tutorial on how to use doxygen. And here is the doxygen documentation of clang.

I like it^^ and it is so easy to use.

While technical documentation arguably does not include an user manual, you may want to consider that as well. If you are familiar with (hardware) specifications, you'll notice that you can have all the information you need, but still lack that one bit: how to use all the functions to do what you want.
Think about creating examples, related functions, dependencies interesting to the user etc.

As for doxygen: it sucks from the reader's perspective. You need to be overly obvious if you want an unfamiliar user to have some chance at finding what he seeks without having to browse half the pages on average. (I prefer naturaldocs for that and several other reasons)

@Combuster:

That's really the kind of thing I'm trying to write. My kernel is extremely small (~800 lines without comments and empty lines), and fairly well commented, so I don't think there will be many problems understanding each function individually. As I said, the API docs are trivial, and I don't need help with that. This would probably be enough for just documenting it for myself or a familiarized developer. However, I want my OS to have users, and I expect they will be able to and want to understand and modify parts of the system. That's why I want to write a user manual that explains all of the internal mechanisms too.