ServerAtSchool Installation Guide
Prev Next

Appendix C. How the ServerAtSchool documentation was written

Contents

1. Introduction

2. INSTALL.TXT and taking notes

3. Documenting the documentation

4. Writing the documentation

5. The Exemplum Primary School

6. Tools

1. Introduction

Because good documentation is so essential in Open Source projects (or any project for that matter), we thought it would be a good idea to elaborate a bit on the writing process of this documentation, in the hope it will inspire others. We also list a few of the tools we used to manipulate text and images.

(top)

2. INSTALL.TXT and taking notes

When the ServerAtSchool software was ready for installation, we had a 2-page document called INSTALL.TXT which described, very basically, the installation procedure.

The very first installation of a ServerAtSchool server was done on the basis of this document, which immediately proved insufficient. It was difficult to determine the correct order in which steps should be taken. Furtermore, that first time we kept switching back and forth between reconfiguring the various subsystems. Very inefficient.

We then decided to write down every step we took with the second installation. Whoah, was that a time-consuming way of configuring a server! However, with the third installation we could follow the notes we took on the second one. It certainly made life easier and configuration quicker. This procedure was repeated with the fourth server we installed. Our notes improved a lot in the process. When the first four servers were up and running, we reached the following conclusions.

(top)

3. Documenting the documentation

Before we started converting our notes and actually writing the documentation, we needed to have some guidelines for a more or less standardised format. This eventually led to a document called Guidelines for writing ServerAtSchool-documentation.

These guidelines were based on the KISS Principle: 'Keep It Simple, Stupid'. We decided to write the documentation using the HTML format for the following reasons.

(top)

4. Writing the documentation

When the guidelines were ready, Peter started writing the ServerAtSchool Installation Guide. Dirk acted as the proofreader who came up with (sometimes stupid) questions, did not understand procedures, and needed more information. Dirk also wrote most of the basic material for the ServerAtSchool User Manual which in turn was proofread and improved by Peter.

Gradually the definition of the target audience emerged: the slightly above-average computer user, who can handle an editor and has a basic understanding of Linux. That would be about the same audience Gerhard Mourani addresses in his book Securing and Optimizing Linux: The Hacking Solution.

As the text got into shape it became necessary to have a sample server (and even a sample LAN) on which to test the instructions in the documentation. Nothing is more frustrating than having software documentation that almost, but not exactly matches the actual events on the computer monitor. This means that the screen shots should be taken from a 'real' installation and not from a 'theoretical' server or, even worse, be manually constructed.

Rereading the text and installing the software on the sample server led to new questions, corrections and suggestions for improving the documentation. These were incorporated in the text or rejected and another sample installation was carried out. In some cases the comments on the documentation even led to minor improvements in the software.

Although we first wrote the Installation Guide and then focused on the User Manual, the interaction between writing, installing and rewriting affected both. A final check was necessary to see if everything matched. This led to minor corrections and additions.

Finally, we had a text which we thought would be good enough for our target audience. Of course, you are the judge of this.

(top)

5. The Exemplum Primary School

An important part of designing the documentation involved inventing a school that could be used to illustrate the various aspects of the configuration of ServerAtSchool. It can be very hard, especially when you are a beginner, to determine where and how to adapt an example to your own situation. Furthermore, if everything is called an example, it can be very difficult to tell what the author is trying to say. We dealt with that problem by inventing our own 'Exemplum Primary School'. Here are some facts about this (imaginary) school:

Exemplum Primary School
Name and address: Exemplum Primary School
1, Rock Bottom street
Gummersbach
http://www.exemplum.serveratschool.net
info@exemplum.serveratschool.net
Headmaster: Mr. Albus Dumbledore
Headmistress: Miss Amelia Cackle
Caretaker: Mr. Freddie Frinton
Teachers: Honorine Hermelin Grønbech, Anna Maria van Schurman, Mary Astell, Wilhelmina Bladergroen, Maria Montessori, Helen Parkhurst, Ovide Decroly, Lev Vygotsky, Peter Petersen, Célestin Freinet, Burrhus Frederic Skinner, Paolo Freire, Ivan Illich
Pupils: Dolly Madison, Miriam Louise Rothschild, Caroline Lucretia Herschel, Martha Jane Cannary, Alicia Boole, Catharina Giacomo, Elizabeth Barrett, Isabelle Sojourner, Abigail Adams, Elisabeth Inchbald, Mary Wollenstonecraft, Virginia Woolf, Evita Peron, Alice Longworth, Catherine Hayes, Georgina King, May Sinclair, Gladys Aylward, Edith Newborn Jones, Mary Kingsley, Henrietta Barnett, Elisabeth Keckley, Mary Fields, Hanna More, Harold Bell Wright, Michael Faraday, William Blake, Oliver Heaviside, Irving J. Gill, Alexander McKay, Howard Carter, Bipin Chandra, Andrew Reese, William Bradford, Herbert Spencer, Branwell Bronte, Sri Nisargadatta Mahara, Simon Newcomb, William R. Morris, Edward Emerson Barnard, Thomas Johnson, Caesar Rodney, William Tilghman, Horace Beam Piper, Ludovico Ferrari, André Marie Ampère, Jaroslav Seifert, Khalil Gibran, Charles Haddon Spurgeon
Canonical servername: praeceptor.exemplum.serveratschool.net

So far you have met only Freddie Frinton, in his role as local system administrator. You will meet the rest of the school population in the ServerAtSchool User Manual.

(top)

6. Tools

We created the documentation using various computers, sometimes Linux-based and sometimes running Windows 98.

6.1 Linux

We used various tools to write and construct the documentation. Apart from the standard tools you can use to quickly and efficiently manipulate text, such as emacs(1), nano(1), vi(1) grep(1), sort(1), sed(1) and tr(1) and standard tools to manipulate graphics, such as pnmtopng, we used the following tools.

6.2 Windows

Apart from the standard tools available on any Windows machine, we used the following tools.

(top)

Prev Home Next
Appendix B. Bibliography   Appendix D. Worksheets

Authors: Peter Fokker <peter (at) berestijn.nl> and Dirk Schouten <schoutdi (at) knoware.nl>
$Id: documenting.html,v 1.10 2006/03/31 15:35:47 peter Exp $