SlickEdit Help/User Guide

[AdrianusV]

My organization has been using Microsoft Word to create user manuals for the past few years.  The problem is these were simply converted into PDF documents and place in the Help file of our flagship product as PDFs.  Now that I'm entering the software side (I've been doing embedded firmware here for some time), I want to do it right and have a PDF manual available, but have context sensitive help, much like SlickEdit does.  I've looked at various products to convert Word files into CHM, but they all require quite a bit of editting after conversion to get them looking as I want them (with links similar to what you label as "You are here: Introduction > ... ").  I'm considering just dumping the current documentation and rewriting it in a more portable format (i.e. HTML) and creating the different documentation types from there.

My question, although not specifically tied to the SlickEdit product, is how you take your HTML files and format them properly for the display in the help and again for the PDF User Guide?  Do you use a third-party tool to do it, or do you manually do it somehow?

Thanks in advance for any guidance you can offer.  One of the main reasons one of the other engineers likes your product is specifically because of the completeness of Help and how it is identical to the User Guide (which he printed out for himself), so I thought it'd be a good place to ask for some feedback.

A.J.

P.S.: Sorry if this is the wrong thread for this - it's not really "General Programming", but it doesn't really fit into the "SlickEdit®" category either.

[Lisa]

Hi A.J. - thank you for your kind comments about our documentation! I am always thrilled to get positive feedback.

Currently we author the doc source files in FrameMaker, which organizes the individual files into a "book". If you are coming from Word, you would probably love FM. It has all the formatting features you love in Word but it is built just for this purpose, so it is more powerful and feature-rich. It gives you more control and more precise control over your docs. There is a bit of a learning curve to the app though. I had some training and would highly recommend it. A lot of the functionality isn't as visible or intuitive as you might expect and you might not discover on your own except after a lot of trial and error.

Using FrameMaker, you can print the "book" to PDF (hence, the User Guide). We use RoboHelp for FrameMaker to create the CHM file used on Windows and HTML files used on the UNIX platforms. RoboHelp does this automatically using the FrameMaker files, and also adds the breadcrumbs you mentioned. It knows not to include the page numbers or other PDF-related settings.

However, we plan to switch to DocBook soon. DocBook is a DTD set that includes both SGML and XML versions which are used to create technical documentation in a variety of outputs. There is a bit of a learning curve due to the back-end processes. It's not as simple as learning and using the tags, as some people have said about it, for me anyway (if all I had to do was write material, sure, it would be a piece of cake). However, this is a good format for source files if you need a variety of outputs. We already use DocBook for our SlickEdit Plug-In product. Eclipse works really well with DocBook for the Help integration.

Context-sensitive Help is another matter. In order to achieve this, currently we take the RoboHelp-generated output and process it against a script that Clark wrote, which pulls in all of the necessary API documentation and adds the two "Functions by Category" nodes at the bottom of the Help > Contents. I'm not sure about the details behind the script; it just works

For our SlickEdit Tools product (for Visual Studio), we use HelpStudio Lite. This is a tool that comes with the Visual Studio SDK and it is a really sleek GUI-oriented system. Everything is very easy to use and intuitive (like most Microsoft apps I guess). The only drawback to the Lite version is that you cannot create a PDF of the entire source. You would have to buy the full version of HelpStudio to get that capability. I've read the datasheet for the full version and it's packed full of features and looks awesome.

Thank you again for the feedback. Good luck!

Links for more info:
(FrameMaker/RoboHelp)
http://www.adobe.com/products/framemaker/
http://www.adobe.com/products/robohelp/

(DocBook)
http://www.oasis-open.org/docbook/intro.shtml
http://www.docbook.org/tdg/en/html/docbook.html

(HelpStudio)
http://www.innovasys.com/products/hs3/overview.aspx

[AdrianusV]

Wow.  Thanks, Lisa.  If I'd known how much work this was going to entail, I may not have volunteered. haha

I will definitely start looking into some of those options.  I personally love the idea of using something like FrameMaker to develop the documentation and then converting it into the formats we want after.  I'm just not sure I can convince management to fork over the $899 to do so (not that I won't try if I like the results of playing around with the trial).

DocBook also seems interesting.  I've heard of it, but never really looked into it.

I guess I have my work cut out for me. 

Thanks again and keep up the great work.

A.J.

[Lisa]

I know what you mean! haha

With all of that, I forgot to mention, for the price, in my opinion, you can't beat using good old HTML to author the source files. You still have utmost control, and there are a lot of products (some even free) that convert HTML to various outputs. Plus if you go with HTML (or DocBook even), you can even use SlickEdit as your authoring tool

[jbhurst]

+1 for using SlickEdit and some kind of markup language. Never underestimate the power and flexibility of plain text formats and plain text tools.

I've done a fair bit of technical writing, lately using both Word and DocBook, and I'll take DocBook+Slick over Word easily, any day. I didn't have to deal with the back-end processing of DocBook, however.

On a recent writing project that required Word, I actually copy/pasted all the text from Word to SlickEdit after each save, and used a couple of macros in Slick so that I could commit a plain text version as well as the Word version into my Subversion repository. The plain text version was far more effective for tracking my changes.

Regards

John Hurst
Wellington, New Zealand

[jbhurst]

P.S. Lisa, you are the star of documentation! The SlickEdit user manual is sooo much better these days!

JH

[Lisa]

That's a good tip, John! We still use Word sometimes for drafts and reviews and I hadn't thought of that. And thanks for the compliment!  *blush* This, coming from the real star, who wrote an entire excellent book on the subject of SlickEdit!