2

Im trying to find a piece of software to help a small (~3-5 people) team write A) a user guide and B) an API reference for the extensible parts of the software. We quite like the idea of using a wiki of some form, but have a few specific requirements:

  • The ability to export the manual(s) into both online and offline readable forms (eg, a bunch of HTML files that can be put on a web server or read locally)

  • Automatically create pages from XML documentation. We are writing in VB.Net/C#.Net, and most of the API specific stuff already has XML documentation comments. It would be great if the API portion of the manual could specify the classes, methods, arguments etc, but also allow the writers to link to these pages from others. (eg, have a page that details the foo class, and be able to have a page that details how to do some general task with the API link to the page for the foo.increaseBarCount() method).

That's just about it, other than the obvious ('easy to use', 'do all the writing for me so that i can get out of the tedium of writing technical documentation', 'not cause a global thermonuclear war').

Does such a piece of software exist? Can a similar system be cobbled together using mediawiki extensions?

insertjokehere
  • 367
  • 1
  • 10

2 Answers2

1

As to "automatically create pages from XML documentation", the obvious solution would by doxygen. It creates documentation (HTML, PDF, WinHelp ...) from special doc comments embedded in source code. It handles Javadoc comments, Qt style comments and XML comments. If you generate HTML, the page names are predictable, so easy to link to; doxygen can also create internal links automatically. If you use other formats, you can probably embed some sort of anchor to refer to page names, but I'm not quite sure about that.

With respect to general documentation, we have good experiences with using a wiki. We use MediaWiki (of Wikipedia fame), but any decent wiki will probably do. We have never tried printing it, but Google shows various solutions for printing from MediaWiki, so you can probably make something work without too much hassle.

The main thing we like about using a wiki for docs is that you can easily change them when you detect a mistake; that keeps them fresh. Also, no worries about having an outdated copy.

albert
  • 8,285
  • 3
  • 19
  • 32
sleske
  • 81,358
  • 34
  • 189
  • 227
  • 1
    Ive decided to go with something like this, but using Microsofts 'Sandcastle' to generate the docs instead of Doxygen, and Mediawiki as suggested – insertjokehere Mar 03 '11 at 09:14
  • Hi, good to hear that you found something that works for you. From what I can gather, Sandcastle is fairly similar to Doxygen, just more geared towards .NET. – sleske Mar 03 '11 at 11:33
0

You could check out Atlassian Confluence. I believe that they have a free version (possibly just an offer, so you may end up paying in the long run, don't know) for small teams. They also have an API, so it wouldn't be too hard to write a utility to extract the XML C# documentation and create pages from it using the API, if nothing already exists. The wiki is easy to use and is used quite a bit by open source projects. You can look at the ANTLR Documentation, which is Confluence, for an example.

Tom Quarendon
  • 5,625
  • 5
  • 23
  • 30