| Task: | Documentation |
| Group: | alisond,cc,julieta |
| Stage: | 1 |
Description
A structure for producing and presenting documentation for both
users and system staff.
Report changes
- 2002-05-13
- Updated name and shame tables.
- 2002-04-26
- Added name and shame tables.
- 2002-03-01
- The action list has been amended to show that we
now have a script for DICE RPM documentation under test.
- 2002-02-18
- The logic of our project has changed
substantially, and the report reflects this. In particular, note the
changes to the proposed URLs and the explanation of who the
documentation is targeted at. We also describe the documentation
packed in the rpms.
Issues
What are we talking about?
Before we can produce a structure for DICE documentation, we have to
define what documentation we are referring to, and who it will
be directed at.
Documentation can be:
- written by us (system administrators) for our use, concerning
DICE project development.
- written by us for our use, but concerning DICE system
administration - what we would term Standard Operating
Procedures. How Things Work, How To Do Things, etc.
- written by us for users, concerning DICE project development - for
example, the DICE FAQ.
- written by us for users, concerning the DICE systems and how to
cope with them - for example, a document on how to
read mail on a DICE machine.
- written by users for users - for example a user-maintained FAQ.
(Newsgroups are used in this way in JCMB: users post their systems
problems, and other users answer them.)
- bundled with software - man pages, info
pages, files in /usr/doc, and so on.
Of course a document could fall into more than one category - for
example descriptions of DICE project development may be aimed at both
users and system admins - but we think that the above is the most
useful way of classifying the various sorts of documentation we will
have to deal with.
Although all documentation is important, we reckon that the priority
should be:
- written by us for us
- written by us for users
- bundled with software
- written by users for users
=======
What's important?
After some discussions with various people we now gather that some of
the above categories are regarded as being substantially more
important than others. In descending order of importance:
- The most urgent category: documentation written by us (system
administrators) for our use. Docs concerning DICE project development
already have a home in
http://www.dice.informatics.ed.ac.uk/doc/. Those
concerning DICE system admin are therefore what we
should start concentrating on.
- Docs for users on how to use the DICE systems. This is the second
most urgent category.
- Docs bundled with software. We've given some thought to how to
make all these available on the web. Much of the
report is about this. But we now realise that this is
less urgent than the docs for sysadmin use, so we'll
give it less priority.
- Already done by Jeremy - docs for users concerning the DICE
project and its development.
Where should it be?
We'd like to make all documentation available on the
web. This is certainly the case with the first four of our categories
above. In the case of documents bundled with software, the use of cgi
scripts would allow various formats to be converted to html but there
is no guarantee that we could do this with all document formats that
might be encountered.
Standards
Do we require to define standards for in-house produced documentation?
These may include acceptable formats, templates, publishing method and
location. The format might vary with the publishing method, the
content and the intended audience.
Having discussed this with a selection of task leaders, the opinion
seems to be that this is not a priority issue. Many task
leaders are not as yet certain as to what sort of
documentation they will produce.
Most people were not overly concerned about which format they would
use for writing their documentation. One keen task leader
wanted to use DocBook format. Others had already tried
it, given up, and gone back to faithful old LaTeX.
Whatever the format used, the end result should be HTML or PDF.
Paul's dicenote LaTeX class is worth using if you want to use
LaTeX. It's a version of the infnote class
which draws an Informatics logo at the
top of the document.
Who Writes it?
It will be the responsibility of the authors to add documentation to
the system. Publishing, i.e. uploading into the system, will be done
using the Informatics web site's CVS-based publishing system.
We will create a page explaining how to create and use the
documentation.
Should we also prepare some user documentation? This has been
suggested in discussions with task leaders and would include a general
"Introduction to Dice" document. The reasoning behind this suggestion
is that some documentation will require input from several tasks and
therefore the documentation team might be in a better position to get
an overview and collate the information.
Documentation Quality
- How do we ensure that documentation is up-to-date ?
It will not be our responsibility to ensure that documentation is
up-to-date. The CVS facilities such as cvsweb will allow
checking of version numbers, uploading dates etc.
- Should locally produced documentation be independently verified prior
to publishing ?
Although this is probably desirable, it is felt that this is outwith the scope
of this task.
- How and to what extent should the publishing of documentation be
automated ?
Documentation will be published automatically wherever possible.
Proposals
A selection of task leaders were approached so that we could try to
establish the nature of the documentation that is going to be
produced. We wanted to find out for each task:
- what documentation for novice user, expert user, system administrator
- will a particular format be preferred for the content
- could it be automatically generated
On the basis of the information gathered above, we intended to prepare
draft templates - guidelines on appropriate content and style for
various sorts of documentation - for discussion. However, many task
leaders either felt that this was a low priority or they were not as
yet in a position to comment.
We want to establish a directory structure on the web server which
classifies the documentation by content/intended audience (basic,
advanced, system staff) and by format (man pages, HOWTO's, info
manuals, rpms etc). We will consider which of these classifications
should take precedence over the other after discussion with task
leaders. We are assuming that documentation will appear under
www.informatics.ed.ac.uk and not www.dice.informatics.ed.ac.uk. We are
suggesting that under /systems there is a 'legacy' page (linking to
the current documentation) and then a 'user' and 'system' page, with
the system page having restricted access. At the DICE meeting on 5
Feb 02 it was decided that restricting access to the system page would
be inappropriate.
LCFG components are best documented at www.lcfg.org/doc, so we should
also link to that site.
The URLs
For the meeting on 5 Feb we proposed that the URL for current DICE
component documentation (components in the sense of identifiable
chunks of DICE, rather than LCFG components) would be:
www.dice.informatics.ed.ac.uk/doc/comp/name.html and
the URL for the release prior to the current release of the DICE
component documentation will be:
www.dice.informatics.ed.ac.uk/doc/comp.old/name.html
and the URL for components not yet released but under test will be:
www.dice.informatics.ed.ac.uk/doc/comp.new/name.html
The "comp"
html files would be automatically produced from pod files extracted
from the rpms (this already happens on www.lcfg.org/doc/).
The script which does this processing needs to know which rpms and
which versions to concern itself with. At present the
www.lcfg.org site uses a manually maintained list but we
would like to know if there could be some way of producing this
automatically.
2002-02-19 update: Lex and Paul have devised a way of producing
the RPM list automatically.
There had been a misunderstanding over 'releases' and, after further
discussion, it has been recommended that, as a priority, we concentrate
on providing only 'current' documentation. This we should achieve in a
similar way to the lcfg site. Older versions would be available
through CVS.
We realised that if people with legacy machines are going to want to
see the DICE documentation (is this necessary?), this means that we
can't just provide a link to the user's own machine (with HTML
"file:" links) because the DICE documentation isn't going to be on
the legacy machines. We therefore need one of two alternatives:
- The simple option is to make sure that the web server itself
is a standard DICE machine, so that it will have all the correct RPM
versions already installed.
-
The more rigorously correct option would be to use a
version of Lex's lcfg.org documentation system whereby a documentation
page generation script consults an automatically nightly generated
list of RPMs, finds the RPMs in /usr/local/{6.2,7.1}/rpms and extracts
doc files from them using rpm2cpio in a temporary directory.
All other system documentation (documentation for system staff
rather than end-users) will be held under:
www.dice.informatics.ed.ac.uk/doc/
User documentation should be held under the following URL:
www.informatics.ed.ac.uk/systems/
2002-02-19
After further discussion with various task leaders, there seems to be
a split in thought over where documentation should be. The majority
feeling so far is that dice.informatics.ed.ac.uk should be used for
project based documentation only. Therefore, documentation for us,
relating to system administration should be under
informatics.ed.ac.uk/systems/sysman. We would also require a
systems/user and a systems/legacy under the informatics web
site. Could we get an agreement on this?
All web based documentation will be controlled by CVS. The publishing
arrangements currently used on the Informatics web server appear to be
suitable for our needs.
We would like to investigate the possibility of creating a FAQ page
which links into information gathered by the faults/support task. We
also would like comments on the idea of a user-managed FAQ addressing general user
questions about DICE. We'd like to know whether a user-managed FAQ,
also contributed to by systems staff, would be sufficient by itself or
whether a separate FAQ managed by systems staff would also be needed.
We will need to incorporate a comprehensive search engine. We
will investigate the search engine tools currently used on the
Informatics web site.
Documentation Feedback
Table 1: Task Documentation Plans Received (thanks!)
| Task | Responsible | Comments, Status | Due Date
|
| Account Management Procedures | neilb | Each of the
procedures in the AMP report will be written up for computing staff | end Jul |
| Account Management Technology | neilb | A number
of documents will be written for computing staff:
- How the technology works and fits together
- How to use the Perl interfaces (written)
- The individual perl
modules are self documenting and can generate man pages via pod2man (written)
| end Jul |
| Default & group environment |
cms |
won't need to produce much documentation | mid Jul |
| Faults/support | cc |
- Description of RT config and recovery procedures
- Docs for support teams on how to use RT, and on cross-site working
procedures
- Docs and web pages for a general audience on how computing support
is going to work
Will probably mostly be written in LATEX using dicenote class
| end Jul |
| Kerberos Infrastructure |
timc |
docs will be bundled in RPMs (written (dice-kadm5)) + Server Recovery document | mid Jul |
| LDAP infrastructure | timc |
docs will be bundled in RPMs + Server Recovery document | mid Jul |
| User web space | neilb |
- A technical document for computing staff on how it all works and
how to manage it
- A document for users on how to use the service, and what they can and
can't do.
| end Jul |
| Legacy System Issues | johnb,iain |
- Each procedure or modification needed to get the legacy world interacting
with the DICE world will be noted for other SB/FH Computing staff in case it
needs replicated. There will be a web page on the legacy www.dai server for
ex-dai
- produce a couple of web pages which should document
what's happening. These will initially at least live under
www.dcs.ed.ac.u, probably in the support homepage and I think all I've
be looking for from dice would be a suitable link from the dice pages.
| End Jul |
| LCFG Technology | paul |
- DICE & LCFG software guidelines (written)
- Building DICE and LCFG software (written)
- Writing LCFG components (written)
- Using LCFG Tutorial (in progress)
- Lots of auto-generated stuff - see lcfg.org
- Document on dial-up (written)
- Document on using laptops (extracted from old stuff)
| mid Jul |
| User Account Transitional Requirements | jmho |
- create ordinary text/html newsletter/announcements under deploy
- Documentation team to put link from doc to the above documents
| end Jul |
| Printing | toby |
- man pages
- docs for sysadmins explaining how all the printing stuff fits together
- docs for users
| end Jul |
| Linux Platform Support | ajs |
- information on supported hardware for general audience
- release notes etc for each release (e.g. rh7.1) for general audience
- installation instructions for CO/CSOs
- which LCFG headers mean what for CO/CSOs
- How LCFG headers are structured for CO/CSOs
- Information on profile server for CO/CSOs
| end Jul |
| Software Management | ajs |
- information on writing RPMs for general audience
- How to submit RPMs for installation for general audience
- information on packages (master and slaves) for CO/CSOs
- How to add RPMs to the system for CO/CSOs
- How to manage user submitted RPMs for CO/CSOs
- Information on bugs management server for CO/CSOs
| mid Jul |
| File System Maps/Issues | bill |
- Set of DICE mount points (user and sysadmin level)
- symlink component (user and sysadmin level)
- amd/ldap (sysadmin level)
- laptops and remote file system mounts (user level)
- an overview of file system mounting
| end Jul |
| Authorisation | sxw |
- Document on how authorisation system works
| end Jul |
| SSH Public Key distribution | sxw |
- No specific document to be prepared for this
| OK |
| Technology for updating config files | sxw |
- rfe documentation over and above existing man pages
| mid Jul |
| Mail hub | jeremy |
No docs needed | |
Table 2: Replies received (thanks) but we
don't have details for one reason or another
| Task | Responsible |
| Beowulf | iainr |
| Mail issues/root mail collation | morna |
| Network | gdmr |
Table 3: No Response From These Tasks Yet!
| Task | Responsible |
| Applications | roger |
| Apps at BP | roger |
| Apps at FH/SB | gordon |
| Common Home Directories | roger |
Dependencies
We're dependent on EVERY project for documentation, but major
dependencies include:
Actions
Current
- 2002-03-01
- Test a script for automating the publishing of
DICE rpm documentation
- 2002-02-05
- Who the documentation is targetted at and how
to split it
- 2002-02-05
- How to indicate current and old releases
|
|
Please contact us with any
comments or corrections.
Unless explicitly stated otherwise, all material is
copyright The University of Edinburgh
|
|
