Resources - Using Doc-O-Matic in a Team Development Environment

Preparing the Environment

For the most part managing a Doc-O-Matic project in a team environment is no different from managing source or API projects you work with using Visual Studio, CodeGear/Borland RAD Studio or other IDEs.

Someone in the team will be the designated project manager for a Doc-O-Matic project. Only this person changes the project files and maintains the project setup. Other users may change source files and documentation files.

In-Source Documentation

For developers documenting source using comments nothing changes at all. They will be contributing to the documentation by adding source comments in the source code. Doc-O-Matic will pick this upon output generation.

Developers can use Doc-O-Matic to author the in-source documentation of course. Doc-O-Matic makes it easy to add and edit comments, providing a WYSIWYG editor that lifts the burden of formatting comments properly because this is all done by Doc-O-Matic. The project manager defines how comments should look like ensuring a uniform look-and-feel for all comments in the source code.

Basic Considerations for Off-Source Documentation

Only one user should edit a certain DTX at a time. The team should be organized in a way to avoid editing a DTX file multiple times at the same time. Multiple edits of the same DTX file will most likely lead to corrupt documentation as it's not as easy to merge changes in DTX files as it is with source files. We do recommend to lock a DTX file for editing for other authors once an author decided to work on it.

Doc-O-Matic will be able to maintain any project, regardless of which approach you are going for.

Off-Source Documentation Approaches

When working with off-source documentation, there should be some decisions be made before you start with the team. Basically it's about making a decision on how finely partitioned the documentation files should be, here are some possibilities:

Approach 1 - One file per Symbol: The most flexible way is to keep each symbol's documentation in a separate source file. It can't get any more flexible than that but there can be a lot of documentation files around. On the other hand this approach can work very well if planned correctly. The documentation should be kept in a different folder structure which resembles the symbol hierarchy in a way (namespace -> class -> member).

Approach 2 - One File per Source File: This approach significantly reduces the number of documentation files while providing a reasonable and logical separation between documentation files at the same time. While it is not as flexible as approach 1, the documentation is still stored in a very decentralized way. The documentation files can either be kept with the source files or in a separate directory structure which resembles the source files folder structure.

Approach 3 - One File per Module: If you prefer as little as possible documentation files you can organize the documentation in larger chunks, for example per source module. This brings the advantage of less files to take care of. The downside of this approach is that a lot of documentation is locked while an author edits content in a certain file.

It should be noted that regardless of which approach you choose, Doc-O-Matic will work equally well and provide you with the same functionality and feature set. The approaches above simply are different ways to organize the documentation files. The only difference is the way you have to organize the inter-team communications to implement documentation file locks and check-ins.

Authoring Team Size

It also depends on the authoring team size. If there are many authors in the team working on the same set of files, it's better to have more files to avoid lock-and-wait scenarios.

On the other hand, if there are only a small number of authors working on off-source documentation it is easy to establish communication channels. That allows for maintaining the documentation in larger chunks without having to wait for a lock to be released on a certain file for a long period of time.

Recommendations

The more documentation files the project is split into the more flexible the project becomes with respect to multiple authors creating content for it. If you are in doubt we recommend favoring an approach with more files rather than less.

Doc-O-Matic will maintain projects regardless of what approach you use. It is not important how many documentation files it contains. Generally speaking you should probably lean towards approach 1 or 2 unless you have a very small team of authors in which case approach 3 could be suitable as well.