David Chart 2001

How to Help Write AbiWord Documentation

This document is an attempt to help people to help us write help documentation for AbiWord. I hope it's helpful. Ahem. This version was written on June 14th 2001; if you are reading it a long time after that, it is worth checking to see whether there is a later version.

Subscribing to the Documentation List

The first thing to do is to subscribe to the abiword-docs mailing list. The information for this list is at:

http://www.abisource.com/mailman/listinfo/abiword-docs

This is the place to ask questions about documentation. It is not the place to ask questions about using AbiWord; the abiword-user list is for that.

Getting the Current Documentation

The new AbiWord documentation is stored in the Abisource CVS repository, in the module abiword-docs. If you want to help with the documentation, you will need to download this module. It would help if you also had a CVS build of AbiWord, but that is not essential.

The following instructions are for UNIX (GNU/Linux at least, probably *BSD as well). I don't know how this applies to Windows. Lines preceded by a '$' are lines you should type; the $ represents the prompt. Other lines are responses from the server or program.

Create a directory in which you will keep the AbiWord documents. In a terminal, type the following:
$ cd wherever/you/want [Substitute a real directory path, of course.]
$ mkdir helpfiles [Or whatever you want to call the directory.]
$ cd helpfiles

Set the environment variable CVSROOT, which tells the CVS program where the files are. For a bash-type shell, type the following:
$ CVSROOT=:pserver:anoncvs@cvs.abisource.com:/cvsroot
$ export CVSROOT

You now need to log in to the CVS server. You only need to do this once. You will be logging in as an anonymous user, which means that you can download, but not upload.
$ cvs login
(Logging in to anoncvs@cvs.abisource.com)
CVS password:
Enter "anoncvs", without quotes.

You are now logged in to the server. You can now download the docs.
$ cvs checkout abiword-docs
This should produce quite a lot of output, as the CVS program tells you about all the files it is downloading.

You now have the files. To update them when things have changed, do the following:
$ cd wherever/you/want/helpfiles
$ cvs update -dP

Updating the Documentation

Once you have written some new docs, they must be added to the CVS repository. If you have commit access, you know what to do.

If you don't, attach the docs to an email (compressed if necessary -- don't forget that you can save gzipped AbiWord files from the AbiWord save dialog) and send them to the mailing list. Someone who does have commit access will look at them and, if they are OK, add them to the repository. They may make minor changes if they spot typos and such, but are unlikely to make major revisions at this point.

To get commit access to CVS, write lots of docs. A few weeks after everyone decides you need commit access, someone will get around to giving it to you. Patience is a virtue!

Licenses and Copyright

The copyright to the documentation remains with the authors and editors. However, the documentation will all be distributed under the GNU Free Documentation License. If you are not happy with that, don't send documents in. Any documents we are sent will be assumed to be submitted on those terms.

Please put your name and the year at the top of any help docs you write, so that whoever converts them to XHTML will know what to put in the copyright declaration. If you edit the document, put your name after the original author's. If more than one person edits a document, the editors' names should be in alphabetical order after the original author's name.

Problems and Requests

The documentation is not perfect. At the moment, a major reason for that is that it hasn't all been written. However, there are bound to be errors, especially as the developers improve the program and change the way things work.

If you have found a problem in the documentation, please use the AbiWord Bugzilla at

http://bugzilla.abisource.com/

to report it. You will need to create a bugzilla account; the process is quite painless.

When reporting the problem, set the 'Component' field to Doc-Content, so that we can find it easily. Otherwise, follow the usual bug reporting conventions. If we've got something wrong, that's a bug. If there's something we haven't documented yet, that's a request for enhancement.

Don't just mention problems on the docs mailing list. While that list is archived, it isn't as easy to search as bugzilla, and things get forgotten.

What to Write

This is the section most likely to become out of date. If the documents it asks for help with have already been done, then it is out of date.

We are starting the documentation by writing 'function-based' documents. That means that we are writing documents explaining how all the menu commands and buttons work. This is being done first so that all the documentation people actually know how the program works.

Once that is done, we will write a tutorial and task-based documents. Task-based documents tell the user how to do a specific thing, such as exchange files with Word users. If you are just getting started, task-based documentation is the place to look. These documents tend to be self-contained, unlike the tutorial, which has to fit together as an organic whole.

To start with, write your documents in AbiWord, using the built-in styles. Look at the documents that have already been done to get an idea of how the styles are used.

dPOWs

dPOWs are 'documentation Projects of the Week'. The original POW concept is explained at

http://www.abisource.com/pow.phtml

The idea is that these are fairly small projects, which don't require a huge amount of background. If there's an unclaimed dPOW that you would like to take, post a ZAP message to the docs list. When you've done it, post the relevant docs along with a SHAZAM, to say it's done.

How to Write

Some hints and tips.

Nothing is obvious. Explain how to do everything. Remember, people are reading the help files because they don't know how to do something. Most people reading the documentation are not computer experts, and certainly are not AbiWord experts.

Read what's already been done. The documentation should be fairly consistent in style and tone. Reading the current documentation will also help to explain what the first point actually means.

Only write in your native language. The documentation is being written originally in English. If that isn't your native language, you can earn undying gratitude by translating the documentation into your native language.