Table of Contents
Writing a tutorial is a good way to learn a topic and a good way to hone your authoring skills. In addition, you will get the satisfaction of knowing that others will benefit from something you have created, that is, not just current and future members of our school, but people from all over the world.
Full-length tutorials are a great way to learn a topic since writing them generally requires a more in-depth understanding of the subject. They provide something really useful to the computing community, especially if no other tutorial of equal or higher quality exists. The drawback is that they require a much heavier investment in terms of time and effort than say, for writing a quicky or doing a translation.
Quickies, in the context of this tutorials collection, are short tutorials with high informational content that are lighter and less formal than a full-length tutorial, the topics will generally be more focused and the applications more specific. Examples could include using some tool to make a snazzy gif image for a web page, doing fancy substitutes in XEmacs, using the java debugger, securing a Unix box, doing something really useful with perl etc. Note too that quikies can evolve into full-blown tutorials with time. etc.
As part of the automated build proces, the tutorials must be written in XML DocBook (see below). It is likely that there will be people who want to contribute yet don't have experience in writing XML DocBook, this is OK. If we get some translators, these contributors can submit their tutorials in pretty much any cut-and-pastable format and have one of our translators convert the file to XML DocBook. Translating documents into XML DocBook can be a bit tedious but since a good translation generally requires that the translator read the tutorial through, the translator gets to learn something in the process.
![[Note]](../images/note.png) | Note |
|---|---|
It is possible to translate quickly by only marking up things like paragraphs and sections but adding things like emphasis typically requires contextual knowledge of the word to be emphasised and hence a more thorough reading. DocBook is a rich markup language, it makes sense to use and benefit from this fact when translating into it. | |
Translation is beneficial to the non-DocBook literate person too because when they get their tutorial back in XML DocBook it should be relatively easy for them to extropolate from this should they want to write another tutorial.
The process of getting involved should be quite informal and friendly but some kind of structure is necessary else nothing will get done. As a consequence I have formalised the process slightly and it can be summarised thus:
The first step is to think of an idea, some of the best ideas are intuitive so it is probably not a good idea to sit down and contrive one, it is a good idea to write about something you know a lot about. It would be nice if you could contribute something that only you can.
Write a brief summary of your idea and sent it to me via email, perhaps at some later date a web frontend for idea submission will be added, but for now, email will be sufficient. I will read the email and discuss it with my boss (Alan Sexton) and we will come to a decision as to whether we think the tutorial idea is good enough, assuming it is, the idea will be added to the tutorials list. Assuming you want to work on the tutorial, and are ready, you will be added to the tutorial group so you can checkout your tutorial via CVS. I will create the CVS module, in addition a document template will be created if you have don't have initial files to commit. This is of course, assuming you want to work on the tutorial, there is nothing to stop you from just submitting ideas for others to work on.
A list of the tutorials will be kept in this document which will detail which tutorials are being worked on and by whom, you can check this list to see who is working on a given tutorial or check the list of tutorials not yet assigned authors and if one takes your fancy, request that you be assigned ownership.
Once you are in the tutorial group, you will be able to access the repository and checkout your own project, make modifications and commit any changes. This can be done like so:
Install CVS: CVS Tutorial
To access from within the CS department, set CVSROOT to point to the repository:
setenv CVSROOT /bham/htdocs/supportweb/documentation/tutorials/cvsrepos/
To access from outside of the CS department, set CVSROOT to:
<USERNAME>@dipsy.cs.bham.ac.uk:/bham/htdocs/supportweb/documentation/tutorials/cvsrepos/
Set CVS_RSH to ssh, so if you are using Windows you need a windows version of ssh.
Issue CVS commands as normal, for example, to checkout the Ant module:
cvs checkout ant
This will create the directory ant containing a copy of the files that the module is comprised of, this is your personal copy and you can do what you like with it and it will not affect the real copy but if you do a cvs commit the changes will be committed to the real copy. (Stating the obvious I know, but worth stating) Luckily, one of the main reasons for using CVS is its ability to recover from such things, but please try your hardest not to perform such accidents.
The tutorials are built automatically at 3AM every morning so please make sure you validate your XML document before commiting changes else it is likely to break the build process (Don't worry, I get mailed a report of the nightly build hence can fix things in the morning if they go wrong).
Being a member of the tutorial group, you will be able to checkout all tutorials in the system, this can be useful if you want to see how somebody acheived something in their tutorial, if you are a first time commiter it is probably worth checking out some of the well established tutorials to get a general feel for the preferred DocBook style. Please don't modify the tutorials of others however without first getting permission from that person.
DocBook 4.2 (The latest version) must be used to markup the tutorials as currently no other DTD's are installed.
Here is DocBook: The Definitive Guide, a very useful resource: http://www.docbook.org/tdg/en/html/docbook.html.
All files referenced from the tutorial such as example programs and so on must be placed in a directory called files in the same directory as the source file, all images must be placed in a directory called files/images. (Note that each tutorial has these directories, created by you, not some central repository of files and images).
The XML file for the tutorial must match the ID of the particular tutorial for it to be build correctly. If multiple olinked XML files are used for a single tutorial, the root of the collection must match the ID of the particular tutorial. ID's are case sensitive but are currently all lower case to avoid confusion.
Feel free to look at the source code for the project but please don't modify it since I solicit full control over it. (It is actually owned by the University Of Birmingham). You can find the full project implementation details here: Project Implementation Details