CERN Accelerating science

This website is no longer maintained. Its content may be obsolete. Please visit http://home.cern/ for current CERN information.



next up previous
Next: General Up: No Title Previous: No Title

Letters to the Editor

Computer Documentation
 

I've two remarks or wish-list items:

-
The CNL page that used to announce new/updated manuals seems to have disappeared. Could we have some mechanism that tells whenever a new/updated manual becomes available?

-
I strongly suggest including a history of changes in the manuals.

Helge Meinhard ECP/SA

Both remarks are probably a good idea. You will see, in this issue of the CNL, a new chapter, at the end, on ``Computer Documentation'', concerning the CERN writeups and manuals, and also all the computing books which are purchasable from the UCO (Computer Documentation Office).

From now on, this chapter will appear on a regular basis, and will contain announcements concerning new documentation (e.g. the ``Guide for the Usage of X at CERN'' in this CNL issue), or the availability of new books (the ``UCO Book Catalogue'' will also be put regularly at the end of the CNL).

For the second point, it will be up to the author or the person responsible for the writeups and manuals to send me a short article to be put in this dedicated chapter whenever they feel some information has to be given (new version, history of changes, etc.) On the other hand, the old way of indicating changes is probably no longer adequate, as explained by Michel hereafter. Nicole Cremel

Faced with an ever increasing flow of information it has become even more necessary to have access to the latest version of the description of a program, detector, the phone book, etc. Guaranteeing the correctness of this information and keeping it up-to-date is one of the main tasks that any organization is facing nowadays. New tools, like printing on demand, electronic documents, multi-purpose publishing formats, are becoming available (see my article on Acrobat for a promising commercial solution), and CERN is looking at how best to apply these emerging technologies. As far as your second point goes, it no longer makes sense to have ``change bars'' a ``history section'' in manuals, since we are continuously making updates to them. In some cases the documentation is even being integrated with the actual computer code, and modifications are made together to the code and the documentation, so that the notion of an ``old'' and ``new'' copy of a reference manual is no longer applicable. Also, since we make small print runs for the various manuals, we always print the most up-to-date version, and it would be uninformative to mark changes with the version of a few days earlier. And finally, we are moving more and more away from ``paper'' printing, and want to introduce tools based on data-base publishing, that allow the user to interrogate a data-base of keywords, routines, procedural parameters, etc., thus making it easier to retrieve the information one is after.

All this will take us a long way from the traditional paper-copy paradigm, but I am confident that the change will be for the better, by ensuring that the user always gets the most up-to-date version of the information required.

Michel Goossens



next up previous
Next: General Up: No Title Previous: No Title



Janne Saarela
Fri May 19 16:03:15 METDST 1995