DataObjects.Net v4 manual

Finally, we started with long awaited DataObjects.Net v4 full-fledged manual.

But before we started we had spent lot of time in discussions about tools to be used for manual creating.
Three options were suggested:

Microsoft Word approach

Use Microsoft Word for editing then export as HTML and clean up the resulting HTML from Word-ish garbage.

Advantages:

• WYSIWYG;
• Easy editing & formatting;
• Proofing;
• Inserts images;
• Inserts highlighted source code from Visual Studio.

Disadvantages:

• You must run “Export to HTML” & make a cleanup every time you want to view page in browser;
• Almost no version control;
• Difficult to make references between resulting HTML pages;
• Difficult to manage inserted images.

Wiki approach

Use Wiki to build the whole manual then grab its content and convert into local HTML pages.

Advantages:

• No need for local editors, just your browser and you;
• Simple version control;
• Supports highlighting of source code fragments.

Disadvantages:

• Grabbing & converting wiki into manual is not a trivial task;
• No proofing (proofing can be provided by some browsers while writing text in textarea control);
• Wiki markup (you are to know it to format your text).

Plain HTML approach

Advantages:

• There are a lot of WYSIWYG HTML editors that support Microsoft Word’s functionality (formatting, proofing);
• Clean HTML code (you control it);
• You see the resulting HTML at any moment (no need for grabbing or conversion);
• You control where and how your images are placed and named;
• Making references between pages is simple;
• Full version control support as HTML file is a text file.

Disadvantages:

• Good enough HTML editor must be found;
• No support for inserting highlighted source code fragments from Visual Studio.

 

After intense discussions we decided to use Plain HTML approach. Firstly we used SharePoint Designer 2007 as HTML editor, then moved to Visual Studio. At last we found Microsoft Expression Web 3, which actually had been made on top of SharePoint Designer. It is faster than VS and more convenient. I like it except its black theme – it is too dark for me.

One more useful tool that we found is “Copy As HTML” add-in for Visual Studio. It allows you to copy source code from the Code Window and convert it into HTML while preserving syntax highlighting, indentation and background color.

 

And what about you? What tools do you use to write help or manuals? Are there any other, more powerful tools or more convenient ways to do this?

Thanks in advance for your ideas.

CodeProject