User Guides

A user guide contains information about how to install, configure, and make use of a hardware device, system, product, or software application, although sometimes installation, configuration, and troubleshooting instructions might be presented in separate documents. User guides might contain conceptual and reference information as well as sets of steps, or procedures, for performing common operations.

The user guide samples here are single PDF documents and sets of individual HTML files (topics).

Online help samples

IBM Rational Software online help—demonstrates DITA's typical concept, task, and reference structure.

• Source: DITA XML
• Tools: Arbortext XML editor, IBM DITA workbench

• Analyzing source code through static analysis
• Performing an automated code review
• Detecting patterns in Java source code

Programmer's guide sample

Entrust programmer's guide—describes how to use a set of application programming interfaces (APIs) for cryptographic operations in Entrust's Public Key Infrastructure.

• Source: XML (in-house vocabulary based on modular XHTML)
• Tools: XML–to–XSL-FO via XSLT, then XSL-FO–to–PDF via RenderX

• Entrust Security Toolkit for Java

I've included samples of the scripts I used to generate the XSL-FO code in the source code section of this page.

User's guide sample

Section of a user's guide—describes how to integrate plug-ins into the Wind River Workbench developer tool based on the Eclipse Integrated Development Environment (IDE)

• Source: Frame Maker .fm
• Tools: Adobe Distiller via Wind River build infrastructure

• Integrating Eclipse Plug-ins

Administration Guides

An administration guide is really a user guide that's written for a specific audience, the administrator of a computer hardware or software system. An administrator is usually responsible for the installation, configuration, and continuing maintenance of hardware components and software, so the content of an administrator guide contains information appropriate to these tasks.

Administration guide samples

Entrust Identification Server, Entrust Entitlements Server, and Entrust Application Server Runtimes (security extensions for the BEA WebLogic Server and IBM WebSphere Application Server).

• Source: Frame Maker .fm
• Tools: Adobe Distiller via Entrust build infrastructure

• Entrust Identification/Entitlements Server
• Entrust Application Server Runtimes

Reference Documentation

Reference documentation provides its users with categorized information that they can refer to easily when it's needed. Such categorized information includes: API descriptions, configuration settings, policy rules, and so on.

Reference documentation samples

Autodesk Topobase API references (Microsoft compiled HTML Help, .chm files) and feature rules reference (PDF).

• Source: C# embedded comments (APIs), Frame Maker .fm (PDF)
• Tools: Doc-O-Matic (APIs), Adobe Distiller via Autodesk build infrastructure

• Autodesk Topobase API References (43MB zip archive .chm)
• Autodesk Topobase Feature Rule Reference

Source Code

Much of the work I've done with in-house, open source, and commercial documentation processing tools has involved configuration and customization. The processing tools, including several releases of the DITA Open Toolkit, stand-alone XML transformation environments, and a commercial content management system (Ixiasoft DITA CMS), required build scripts, DTDs, XSLT transformation scripts, and on one occasion, a Java application to control XML source transformation and output file rendering.

Source code samples

Rather than add the source code samples to this website, I've committed the files to a GitHub repository. The sample code is in a subdirectoy called source-code. The other subdirectories in the repository contain the sample documents I've described and listed elsewhere on this page.

To see the samples, go to: https://github.com/drewhodge/doc_samples.