Tool to track xml documentation changes

Aug 13, 2009 at 2:32 PM

Here's what we need. We use in code commenting to create a reference guide to our public API.

Ideally we would want to take the Visual Studio generated .xml file, pass it of to our doc department. They can then modify the .xml file without having to have the source code or VS installed and send us back the revised .xml file.

The tool we need would then take this revised.xml I guess compare it to the baseline xml, and commit all changes into the source code.

 

Has anyone heard of such a tool? Does anyone else have this same kind of workflow and has another idea maybe?

 

Thanks

Aug 13, 2009 at 10:25 PM

>>escristian: Has anyone heard of such a tool? Does anyone else have this same kind of workflow and has another idea maybe?
An automatically generated file is not normally used that way, and you can run into maintenance nightmare.

If I have project like this, these will be my options

  1. Recommended: Use external XML documentations: The XML Docs support the use of the include tag,
    which allows you to use localized versions of the documentations. Also, it allows you to have external
    editors or authors. This way, you do not have to keep different versions of the documentations, and you
    can keep them under a source control, such as the VSS or SVN.
  2. Use database for documentations: This is not recommended except if you are a large institution with
    the resources to pull it out. As above, the documentations are not directly added to the source files, but
    in this case you will need other tools for managements and editing.
    For an idea of how Microsoft does this, see Sandcastle Overview

Best regards,
Paul.