Help generation tool with MS Word and C# xmldoc support

Question

I'm looking for a help/documentation generation tool which would satisfy such requirements:

• it should support xmldoc comment produced by c# compiler or (even better) directly support sandcastle
• it should support importing of MS Word documents.
• it should support creating links from conceptual documentation to reference documentation produced from source code.
• it'd be nice if it supports conceptual doc authoring in MS Word

More details. My project is a framework/library for .NET. It has several VS solutions with totally more than 50 C# projects. First of all I want to generate help (chm & help2 & help3 in the future) from the source code of my projects. I'll refer to that documentation as "reference doc". Sandcastle (especially with using SCFB) can do this in very nice way. But (I guess it's very common situation) I have some additional documentation for the framework/library. That documentation is in MS Word files (5-10 files). I'll refer to that documentation as "conceptual doc". I want to produce a solid help system with conceptual doc and reference doc (like MSDN). And I want conceptual part of the help contains links (URL) that refer to reference part of the help for every .NET type name from the framework/library. (Obviously any help system is just HTML eventually).

The problem is how to create these links. MS Word files do not know anything about C# xmldoc. Sandcastle doesn't support Word files. So I have to take some Help Authoring Tool (HAT). By the moment I can't find any aproprient tool for me. And I would be very appreciate for any help!

An stumbling block for all tool is links autocreation. I'd like links be created automatically durining generation (which can take place on build server). Why automatically ? Because it allow easy renaming of types. For an instance. I have some text in conceptual doc: "for accessing request processing context use static property Current of XOperationContext type". Here XOperationContext is a type name. I'd like it became a link (URL) to XOperationContext class's specification in result help system without any significant efforts. I'd like to mark it in Word (probably with some HAT's plugin installed) or in HAT's editor as something like "make this word link if possible". During generation each such word would became a link if there is a type name with such name.

I know about these tools:

• Toolsfactory Doc-o-Matic (using now)
• Innovasys DocumentX and HelpStudio
• ComponentOne Doc-to-Help

Doc-o-Matic support links autocreation. Truly automatically. It tries create a link for each word in PascalCase - brilliantly. But it doesn't support MS Word. Innovasys' and ComponentOne's software do not support creating links automatically. Innovasys' software do not support MS Word (I'm not sure for 100% about this).

I tried to ask on Innovasys' and ComponentOne's forums. No luck so far. Innovasys' soft support scenario like mine: creating conceptual doc in separate tool - HelpStudio and generating help from source code with another tool - DocumentX. But there's no ability to create links automatically and import MS Word files.

So, please share your expirence for that common task (I'm sure it should be common).

p.s. please let me know if I haven't managed to explain my thoughts correctly from English grammar's point of view, I'll try one more.

Answer 1

Try taking a look at SandCastle.

Answer 2

How about exporting your MS Word files to HTML and then merging them into the HTML for the help files? Is that an option? There might some loss of formatting, but it might let you integrate everything a little bit better.

Answer 3

Sandcastle is open source, so why not invent something on your own? Write an office automation tool is not that hard after all. And you can even create a business on that tool.

Answer 4

Have you looked at Doxygen? It doesn't do anything with Word files, but it's open source, so perhaps you could add those features yourself. I really like the docs it produces, and it's very lightweight, so I included it into the build process to regenerate docs automatically.

Answer 5

I think the solution would be to convert your Word files into (X)HTML or another non-binary format first, and then import the conceptual docs along with the reference docs. You can autocreate links based on the text content of the document bodies (as you pointed out) or run the conceptual docs through a preprocessing step to annotate them. This could even be a script run before import.

Answer 6

I would suggest starting with SandCastle and then postprocess one of the output file formats to produce Word documents. Producing Office 2007 Word documents (*.docx) from scratch is not that difficult, once you have a good understanding of how things are packaged. Brian Jones has an excellent blog on the Open XML SDK, which provides support for dealing with Office documents from .NET.

And you can always decide to start with an existing Word document and then replace placeholders with your own text, if creating a full package seems to be too complicated or too much work for what you are trying to accomplish.