Application Documentation

Champaign-Urbana Room, 12:00 
October 28, 1997
Business Development Presentation

Introduction

For some people, writing is hard work, and may involve bad memories of English classes of the past..

A good package with poor documentation is a poor product.

Today's information is available by handout and on the Developer's CD.

What is the first step to writing good documentation?

1. Brainstorming: The Chaos

Image: Index cards

Write down—somewhere, in some manner—everything you want to put in the manual.

Ask these questions when brainstorming. Some of the questions are also useful to consider when programming the application.

After all the thoughts are down, what is next?

2. Outlining: Bringing Order to Chaos

Image: Ruler marked in inches

Restructure the information

Don't start writing yet!!

Organize the list.

Keep basic information first.

Put standard usage information next.

Finish with information for advanced users.

Create the outline

Put the ordered list into an outline.

Avoid heavily-nested outlines. Remember the Help Browser has four levels of hierarchy, and the documentation will be presented in the Help Browser as on-line documentation.

Focus on the breakdown of information; if Section 1.1 exists, there must be a Section 1.2.

Present a moderately even amount of topics in each chapter.

Add examples and definitions as needed.

Documenting the package may bring out problems in the design of the project.

3. Reviewing: Filling in the Holes

Image: Ruler marked in half inches, quarter inches, etc.

Review the outline. You may need to add some additional topics and remove others.

Fill in the outline.

Review the purpose of the instructions and examples.

It is okay to repeat basic information throughout document, but it is also a good idea to refer to a specific section (or an appendix) by name for more information on a particular topic.

Consider writing a glossary or word list.

4. Writing: Laying the Pavement

Now you are ready to write!

Work on one section of the outline at a time (modular writing).

Avoid tangential discussions. Follow the outline that you have produced.

Focus on consistency in documentation.

You can't refer to integration using symbols such as Σ or Π.

Use fonts consistently.

Example

Integrate the function to find the formula for the area under the curve: Integrate[function, x].

Improved example

Integrate the function f using the Integrate command to find the formula for the area under a curve. Type Integrate[f, x], where x is the variable of integration.

Format unnumbered lists identically.

Example

*Make sure you give the variable of integration.
*The Integrate function takes two arguments.
*Don't forget to check that x doesn't have any specific values.

Improved example

• Use two arguments to the Integrate function.
• Give the variable of integration as the second argument.
• Clear the variable of integration to remove any assignments to it.

Use the present tense as much as possible.

Example

You will integrate the function using the Integrate command. You will give it a function and a variable of integration. You will then see the value returned from the kernel.

Improved example

Integrate the function using the Integrate command. The integrand is the first argument to the function. The second argument is the variable of integration.

Use active voice as much as possible. Avoid the passive voice or the subjunctive mood.

Example

It is possible to integrate a function using the Integrate command.
You could integrate your function using Integrate.
A function is integrated with the Integrate command.

Improved example

The Integrate command calculates the integral of a function.

Avoid redundancies.

Example

Also, you can perform definite integration, too.
Our plans for the future include expanding the abilities of the front end.

Improved example

You can perform definition integration as well. 
Our plans include expanding the abilities of the front end.

Spell-check the text in the document.

Refer to customer as "you," but avoid the term "we".

Example

We want you to use the Integrate command.

Improved example

Use the Integrate command.

Loading the package must be the first example in each chapter.

Example

Use the LogPlot command to create a graphic of the natural log function.

LogPlot[Log[x], {x, (1/2), 5}]

Improved example

First load the graphics package. Use the LogPlot command to create a graphic of the natural log function.

<< Graphics`

LogPlot[Log[x], {x, (1/2), 5}]

Use definition boxes early in each chapter to highlight commands.

Example

Use the Integrate command to evaluate integrals. The first argument is the function and the second argument is the variable of integration.

Improved example

({{Integrate[f, x], integrates the function f, where x is the variable of	integration}})

Tables can highlight options quickly and easily.

Example

The Plot command has options such as PlotLabel, Frame, and Axes.

Improved example

({{option name, default value,  }, {Axes, Automatic, whether to include axes}, {Frame, False, whether to draw a frame around the plot}, {PlotLabel, None, \(\(an\ expression\ to\ be\ printed\ as\ a\)\ 

                \(label\ for\ the\ plot\)\)}})

Use numbered lists for step-by-step procedures.

Example

You can save a notebook as a text file. Be sure to give it a name that doesn't end in the .nb extension. Choose Text from the menu if you want to do this.

Improved example

To save a notebook as a text file:

Examples in In and Out sessions are good, but explanatory text beside such sessions should be brief and include complete sentences.

5. Formatting: Adding the Polish

Here is a short list of cell styles defined in the Manual.nb style sheet.

If I am referring to the Integrate command

Tools are available to make the formatting work easier, and there are tools for producing definition boxes and tables. See Andre Kuzniarek's talk tomorrow for a tutorial on these tools.

Resources