Hi,
I need Your help. Can anyone give advice what is the good practice for documenting a large-scale software under special conditions? The project is developed by many programmers, accessing the codes through a classical check-in/check-out system. The existing code is weakly documented.
The code is in C++, important: NO managed classes, NO .NET and this is what excludes many existing, otherwise nice solutions.
I have to come up with a suggested solution, that is consistent with these conditions:
- Essay-like help pages/content are favored over automatically extracted "in-code" document entries. /As a matter of fact, "in code" comments are offered only as "optional" features for some developers. (But we still wish to keep this option.)/
- The source code must contain as few "extra" comment lines as possible. The sources for document pages, longer "essays" are to be stored in different files, without "polluting" the sources.
- Still, we need to compile help files that can be integrated with the Visual Studio's standard help system. (Bringing the appropriate page for our functions under the cursor)
- Some parts of the codes are shared between Windows/Mac/Linux teams, so purely Visual Studio specific solutions are not favored. (More precisely, compilation of the output help files can be either Windows or Visual Studio specific, but tools for creating the input documents cannot.)
- Developers should edit the documentation files in a parallel way by checking them in and out.
- We would like to compile both HTML output format, and Help files for Visual Studio.
I think, the most demanding point is to create help files for plugging into Visual Studio in a context sensitive way without relying on the in-code comments.
Can You recommend good practice and/or software tools for meeting the above requirements?
Thanks in advance,
Gyorgy
I need Your help. Can anyone give advice what is the good practice for documenting a large-scale software under special conditions? The project is developed by many programmers, accessing the codes through a classical check-in/check-out system. The existing code is weakly documented.
The code is in C++, important: NO managed classes, NO .NET and this is what excludes many existing, otherwise nice solutions.
I have to come up with a suggested solution, that is consistent with these conditions:
- Essay-like help pages/content are favored over automatically extracted "in-code" document entries. /As a matter of fact, "in code" comments are offered only as "optional" features for some developers. (But we still wish to keep this option.)/
- The source code must contain as few "extra" comment lines as possible. The sources for document pages, longer "essays" are to be stored in different files, without "polluting" the sources.
- Still, we need to compile help files that can be integrated with the Visual Studio's standard help system. (Bringing the appropriate page for our functions under the cursor)
- Some parts of the codes are shared between Windows/Mac/Linux teams, so purely Visual Studio specific solutions are not favored. (More precisely, compilation of the output help files can be either Windows or Visual Studio specific, but tools for creating the input documents cannot.)
- Developers should edit the documentation files in a parallel way by checking them in and out.
- We would like to compile both HTML output format, and Help files for Visual Studio.
I think, the most demanding point is to create help files for plugging into Visual Studio in a context sensitive way without relying on the in-code comments.
Can You recommend good practice and/or software tools for meeting the above requirements?
Thanks in advance,
Gyorgy
Comment