Surevine make a point of using open source products and indeed try to support the open-source community by encouraging employees to commit fixes to bugs back into public repositories and generally be good open source citizens. So I don’t want this to be read as an attack on all the people who give up their time and money to making open source work, but more as a constructive suggestion how we can all contribute to, what I feel, is a much neglected area in both proprietary and open source products : the documentation.

I think one of the problems with writing documentation is that somebody who knows nothing about the subject in question has nothing to write, the expert however has a whole head full of knowledge he can get down on paper.

The expert will often skip things that he thinks is obvious where the newbie will be completely stuck until someone clarifies things. With this in mind can I suggest :

Get someone who doesn’t understand what you are documenting to read and use your document.

One thing I see quite a lot of is minimal explanation of a number of complex steps followed by a very simple step. For the beginner, this can be very frustrating.

e.g.

Save the commands and options to correctly deploy the product to a file so that in future you can easily redeploy by typing :

./deploy

Anyone reading this who already knows how to create an executable script with the right commands and options probably already knows how to run it. What they don’t know is what to put in that script that is specific to your product.

Other things that are wrong with that are :

• The script might not be called deploy. Maybe it will be called redeploy.sh
• Why will I need to redeploy it?

Those lines could be written as :

The commands and options to deploy should be saved to a script. That script will be used to redeploy the same configuration for other nodes in the cluster. It will ensure that everything is as similar as possible. If you need more information on scripting consult your OS manuals.

The first command to run is ./configure. You should use it with the option –prefix= followed by the location you want the software to live. This location must be the same on all cluster nodes. For example :

./configure –prefix=/usr/local/

etc…

I think that makes the next guideline :

Keep to your own subject. Only describe changes that apply to other components. Don’t go into detail about using/changing peripheral systems.

The last suggestion I’d like to make is :

Don’t go on too long.

People can only concentrate for a short time.

With that, I’ll leave the rest for part two.