locked
Optimal solution for documentation

    Question

  • Hi,

     

    I need Your help, I have to find (suggest) an optimal solution for documenting existing software.

     

    The software is created under Visual Studio, developed by many programmers and is weakly documented at its current state.

    The team manager will prefer using "free-text" based documentation, insted of (for example) Doxygen-like, extracted "in code" comments.

     

    Being able to compile both HTML documentation and MSDN type help files is mandatory. The source code is also distributed between many developers, who will work on their parts, but we need to be able to compile a coherent documentation from their contributions. The projects are expected to grow further in the future, so the solution should be able to cope with really complex structures containing many files, while maintaining a managable interface for keeping the documentation up-to-date.

     

    Price is not the most important aspect, but obviously a cheaper solutions would make me happy. Can You recommend either Microsoft or third-party solutions?

     

    Thank You in advance,

    George

    Wednesday, October 24, 2007 2:00 PM

Answers

  • Hi,

     

    If you're using unmanaged C++ in VS then I think you can still use XML documentation, however you'd have to generate a reflection.org file to use Sandcastle and I don't know of any tools that will automate this for C++, currently.

     

    - Dave

     

    Wednesday, October 24, 2007 4:41 PM

All replies

  • If it's a .NET project, you might want to consider Sandcastle.  See http://www.codeplex.com/DocProject/Wiki/View.aspx?title=Sandcastle%20Help&referringTitle=Home for an introduction to Sandcastle with a lot of useful links to additional information and community tools.  It does make use of XML comments to produce the documentation which can be embedded in the code and extracted into a file by the compiler but you can manage them in external XML files if you really want to do it that way.

     

    Eric

    Wednesday, October 24, 2007 3:42 PM
  • Hi George,

     

    The software is created under Visual Studio, developed by many programmers and is weakly documented at its current state.

    So far you've described most software, in my experience... Smile

     

    The team manager will prefer using "free-text" based documentation, insted of (for example) Doxygen-like, extracted "in code" comments.

    Is there any particular reason why text based documentation is preferred?  Xml documentation is a better choice, especially inside code comments, because:

    1. IntelliSense can automatically show summary and parameter information, which will certainly help maintenance, especially if you're working with spaghetti code that hasn't yet been refactored (comments are invaluable there).
    2. Xml code comments provide more incentive to keep the documentation up to date.
    3. Xml is, as you probably know, a universal format that can be used to easily transform documentation into any other format, including HTML, XHTML, Word, PDF, etc., with the right tools of course.
    4. Xml documentation provides a set of well-known tags, which keeps documentation created by multiple authors at least somewhat consistent.
    5. Compilers will create Xml documentation automatically based on your code comments, which can in turn get passed to Sandcastle to build HTML documentation.
    6. This is not an exhaustive list Smile

    Sandcastle not only produces HTML documentation that looks like MSDN, but it can be customized to produce any presentation style that you may want using XSL transformations and CSS.  And with some additional tools it can also be used to produce a documentation website, Help 1.x and Help 2.x, and really any custom output format that can be generated from XML using XSLT.

     

    Being able to compile both HTML documentation and MSDN type help files is mandatory.

    They are one in the same.

     

    The source code is also distributed between many developers, who will work on their parts, but we need to be able to compile a coherent documentation from their contributions.

    I think that XML code comments make more sense when there are multiple developers, for the reasons stated above.  But for conceptual content, long remarks, examples, and any other type of documentation that is more useful when presented as HTML instead of when read directly in code, I recommend creating external XML documentation, for many of the same reasons stated above.

     

    Using tools such as DocProject or the Help File Builder will allow you to compile documentation from various sources together into a single website, Help 1.x or Help 2.x using Sandcastle and your existing Xml documentation and conceptual topics.

     

    The projects are expected to grow further in the future, so the solution should be able to cope with really complex structures containing many files, while maintaining a manageable interface for keeping the documentation up-to-date.

    DocProject has a built-in XML documentation designer that can be used inside or outside of VS to generate external XML documentation in the form of XML code comments; however, the comments are stored externally from the code in separate XML files.  Simply building the project will automatically include external documentation, which must be written using the same structure and markup as if it was XML code comments, making it easy to manage and integrate the work of multiple developers.

     

    Price is not the most important aspect, but obviously a cheaper solutions would make me happy. Can You recommend either Microsoft or third-party solutions?

    Sandcastle.  Cheaper, like free?  Wink

     

    - Dave

     

    Wednesday, October 24, 2007 4:24 PM
  • Thank You for the quick reply Eric.

    The page You recommended contains a beautiful collection of tools, I'm sure I will use them later for other projects.

    The current project is however not a .NET project. So I am still searching for the optimal solution. Any idea is highly appreciated.

     

    Wednesday, October 24, 2007 4:26 PM
  • Hi,

     

    If you're using unmanaged C++ in VS then I think you can still use XML documentation, however you'd have to generate a reflection.org file to use Sandcastle and I don't know of any tools that will automate this for C++, currently.

     

    - Dave

     

    Wednesday, October 24, 2007 4:41 PM
  • Hi, Dave,

     

    Thank You for the detailed answer, I will try this solution. I hope it will fit to our needs.

     

    George

     

    Thursday, October 25, 2007 8:24 AM