What is API Documentation

I really like this blog posting for the STC Puget Sound chapter that explains what API documentation is all about. Click to read

Single-sourcing strategy I used for a Developer Guide

I utilized single-sourcing for most of my documentation projects. Here is an example of  how I accomplished single-sourcing for a Developer Guide:

1) The document needs to be delivered to two different formats: internal developers as PDF and external developers as HTML. The PDF version includes more topics than the HTML version. To accomplish this, I wrote the source file in DITA XML, and created two different ditamaps: one for PDF and one for HTML. The PDF version ditamap includes several topics that are specific for internal users but most topics are reused by both ditamaps.

2) I used conditional text for content within a topic that is intended for different audiences by applying @audience:

<p audience=”internal”>Information for internal users</p>
<p audience=”external”>Information for external users</p>

3) I used content reference for content duplications. For example: Some APIs have same input parameters. When a parameter was first motioned, I added @id for it:

<p id=”parameterA”>Information about parameter A</p>

If the same parameter appeared later in a different document, I used @conref to reference to it:

<p conref=”filename.xml#topicid/parameterA” />

4) I used application name as a keyword variable in my document to avoid manually updates if the application name changes later. At the beginning of the ditamap, I used to define the application name as a keyword:

<keydef keys="AppName"> 

 <topicmeta>
 <keywords>
 <keyword>ACTIVE Passport</keyword>
 </keywords>
 </topicmeta>
</keydef>

Anywhere in a topic, when needed to mention the application name, I used the reference:

<keyword keyref="AppName"></keyword>

The application name always changes for a new product. If it happens, I only need to change the keyword in the ditamap.

Organizing Web application online help

Organizing help content is a very important part in technical writing. I always find it’s quite challenging and always in the process of making the organization more efficient. These are the main methods that I am using to organize the help content:

·    Organizing by screen: List out all the tasks and topics that relate to each main screen. This organization might help users stuck on a particular screen. We also provide tooltips and FAQ in the major screens to help users to find information faster.

·    Organizing by steps: When creating an event, there are several steps in the wizard. I make each step as a category, and group all the related tasks and topics together under the step, and follow the sequence of the steps.

·    Organizing by related information: Related information contains a series of logically related links placed at the end or along the side of each topic. This method provides navigation directly within the topic, where users often spend the most time.

Other methods that I also might be considering when organizing help content are:

·    Organizing by audience: Audience may be identified by their roles. By doing this, you can present the topics most relevant to that audience.

·    Organizing by skill level: Skill level can be divided into beginning and advanced tasks. Users new to the system can see a list of topics appropriate to beginners, while advanced users can see the more difficult topics.

·    Organizing by format: Format can be grouped by videos, PDF, online help, or other formats. This helps users looking for help material based on their leaning preferences.