2. INSTALL.TXT and taking notes
3. Documenting the documentation
4. Writing the documentation
5. The Exemplum Primary School
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.
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.
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.
|Name and address:||
Exemplum Primary School
1, Rock Bottom street
|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|
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.
tr(1)and standard tools to manipulate graphics, such as
pnmtopng, we used the following tools.
cat /dev/vcsa1 | sd2ppm | pnmtopng > screendump.png.
gnome-panel-screenshotwrites .PNG files.
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 $