C# In-Source Documentation Generation for NON-Programmers

Question

The software group I currently work in has recently decided to start documenting our codebase. The initial approach they have been taking was to use the built in triple slash /// method of documenting.

A newer issue we began to find was that the result of running this through doxygen is a very nice representation of the codebase but for a programmer to use, where we had intended for this documentation to be readable by our Systems Engineers who will often come to us asking what a task is doing exactly.

Is there an easy way to document our code using the /// method and doxygen in a manner that if we run it a certain way, we can generate a document that JUST contains the Systems engineering version of documentation without all the extra fluff of a standard programmers documentation that would scare away a systems guy such as methods and member variables etc.? Any alternative solution suggestions are also welcome.

I'm sorry if this is a little confusing as to what we are trying to accomplish, I can adjust as responses come in. Thank you.

Answer 1

I don't think this is going to get you what you want. It sounds like what you really want is to have good specification documentation that the Systems Engineers can use, and good Unit Tests that validate that the code runs according to those specifications. Inline code documentation is really more for the software engineers.

What's a little surprising and slightly frightening about your question is the implication that the Software Engineers are creating a system that the Systems Engineers will have to use, and that the Software Engineers are creating functionality from nothing. You should use extreme caution with having functionality be defined by your Software Engineers; they should be implementing specified functionality (and that specification should be what is used by the Systems Engineers).

Answer 2

If you're documenting code, then you can assume it's going to be read by programmers. Private members can be stripped from the output, which allows you to document public members as your public documentation. If you're not documenting code, i.e. an end-user interface that is used by non-developers, then I don't think the code is the best place for it.

Answer 3

One thing you can do is to use doxygen's \page command, which gives you "Related Pages". Create a textfile with an extension that is processed by doxygen, and just put a comment in there. (I use .doc, but you might want to change that to something else to avoid confusion with Word documents. I am also putting these files in a common directory called docsrc to have them at one place.) These pages then show up in a seperate section in the docs.

/*!      
\page foobar Foobar calculation

I am using the procedure outlined in the bla bla note to estimate
the foobar in our baz. Lorem ipsum dolor...

\section step1 1. Estimation of the foobar-efficiency of the baz system.

\author jdm
*/

You can then create links to the page or the sections with \ref foobar or \ref step1.

In our project, basically everyone who uses the program also codes around with it, so it is nice to have the usage documentation cross-linked with the code. But as the others pointed out, it might not be the best solution for a typical enduser-documentation.