views:

48

answers:

1

I should preface this by saying that this post should almost surely be a community wiki, though I don't know how to set that up. If someone could change this I would really appreciate it.

We're working on a product that is a web-based application. We'd like to get some conceptual user documentation integrated into the app, preferably as an html-based solution, but there don't seem to be any great options in .NET. Ideally, our solution would allow us to:

  • create indexes automatically, based on page/topic names
  • create a glossary
  • allow easy "wiki-linking" from one topic to another
  • create printable hard copies or PDFs of the entire documentation set
  • update documentation without having to dive into either XML, or some other markup language or transforms (i.e., no XSLT)

Note that this is end-user documentation, and not developer/API documentation

My gut feeling is that the ideal solution would be something like a distributable, non-editable wiki.

It seems like Sandcastle is able to do most of this with its "conceptual documentation," but it is unwieldy to say the least - everything has to be written in MAML, there's no visual editor (or even a simple one, using say, markdown), and linking between documents is difficult. Ditto for Doxygen, I believe.

We've also looked at Sphinx, the python-based doc tool, but if possible we'd like to stick to the .NET stack.

Are there any other tools that I can look at? It seems like a portable wiki-type tool is something that should exist, right?

A: 

Have you heard of Sandcastle?

We use a plugin to generate .chm files called the Sandcastle Help File Builder, but there might be other extensions that better suit your needs.

dana
Yup, I actually mention Sandcastle in the post :) We use Sandcastle (along with the SHFB) to generate our API docs, and it works great, but user-docs are a little different animal.
mjd79
I guess it helps to read the question thoroughly :) You are right, end user documentation is totally different. We use Adobe RoboHelp (http://www.adobe.com/products/robohelp/), but it is not automatically integrated with our development efforts. A separate team updates it as new features are released. As for end users, they have a friendly web-interface to browse through. I would imagine there is PDF support as well (this is Adobe afterall).
dana