Ask STC-Montreal: What are the Best Options for Online Documentation?
Ask STC-Montreal | Posted January 2nd, 2009
Got questions about technical communication? Ask the community of STC-Montreal. Send us your questions for publication. (Questions may be edited.)
Today’s question to STC-Montreal is about creating electronic documentation.
Dear STC-Montreal,
I was just hired as a writer at a company that has never had a full-time technical writer before. So I am starting with a clean slate. We’re not going to be publishing printed manuals, so I need to evaluate the best approaches for electronic documentation.
What are my options for delivering online documentation these days? Is there anything better than old-fashioned CHM files or PDFs? What’s best for readability and searchability? Our product is a desktop application, not a web app.
— Flying Solo
Join the discussion. Leave your ideas and suggestions for “Flying Solo” in the comments below.
January 5th, 2009 at 11:19 am
Posted by Jim Royal.
Dear Flying,
Putting aside the latest developments in Windows-based help (not my strength), there are two options that you may not have considered. Which one works for you depends on how your company’s application is deployed.
The first option is to take a purely online approach. There are a number of sophisticated web-based content management tools — including wikis, blogging engines, and document management systems — that could be used to deliver your product’s documentation. Web-publishing tools have the advantage that they can be updated rapidly, using nothing more than a web browser. Once the infrastructure of the site is built, adding new content is a snap. And the customer always gets the latest information (this can be important, for example, if your company relies on third parties for information or functionality). The challenge with this approach is in designing a web interface that is easy to navigate, that provides useful information in a way that suits the user, and which can grow without needing to be restructured. Wikis, for example, lend themselves more to knowledge bases rather than training material, but a good design can work around that limitation with intelligent organization.
The second option is to take an offline approach using PDF files for more than just printable e-books. PDFs have been pilloried for their poor usability (by people such as Jakob Nielsen), and with good reason. Most PDFs contain pages designed for letter-size paper with small fonts that cannot be read clearly on screen, and which do not even take advantage of the built-in features of Acrobat, such as the table of contents or internal hyperlinking. I would suggest that you look at designing PDFs as purely electronic documents, formatted for the screen (landscape rather than portrait layout), using page layouts and fonts that are suited for on-screen reading. Make use of hyperlinks for cross-references and TOC and indexes. Use colour for informational purposes (since you don’t need to worry about printing costs). Build in a menu of useful links into the page header or footer (such as TOC, Index, Help, Contact Us) much the way you would with a web site. Embed Flash videos for more dynamic training. PDF is often criminally underused, and it is capable of providing a rich experience.
Does anyone else have any other suggestions?
January 6th, 2009 at 6:50 pm
Posted by Andy Gural.
My employer is using a Wiki for the bulk of its documentation. The software is called Confluence and it comes in a variety of flavours and its functionality can be extended through plug-ins.
We will evaluate how best to continue our documentation efforts in the next while as the firm has been without a tech writer for two years and the doc set has been allowed to grow in all sorts of directions. My own preference is for the ‘Restaurant’ methodology of documentation: use a few basic ingredients to come up with a range of dishes. A wiki will have a place for my employer’s docs, but so will discrete documents including PDFs.
PDFs these days can be generated dynamically and can contain multimedia content.
Here’s a link for a comparison of various Wikis: http://www.wikimatrix.org/
January 10th, 2009 at 11:24 am
Posted by Ev Larsen.
Hi Flying:
Jim Royal draws some good distinctions between the dynamism and usability of online publishing vs the more static approach required for PDFs. If you need control and accountability, then PDF is still the way to go, supported by a good document management system if you maintain a large library.
If, however, you’re faced with content that is constantly changing “on the fly” then you should take a look at the possibilites that wikis, web=based help and content management systems (CMSs) offer. Andy’s case is an example of how to start stepping into a more dynamic approach.