On Wed, 10 Jul 1996, Daniel Pead wrote:

> I think this is getting out of proportion.  What is needed desperately is an
> update of the 'Getting Started' and 'Installing RiscBSD' documents so that they
> reflect the current version of the software.  Since these documents are going
> to be used mostly when your computer has its hood up and its wheels off then
> the overriding need is for good *ASCII* versions of these documents.  Forget
> LaTex, HTML and StrongHelp - you may be reading these things from single-user
> RiscBSD mode or even *TYPE commands at the RISC-OS prompt!

I don't quibble with your assertion that as a first step we need good
installation documentation delivered to the end user in plain ASCII
form. I made that point in my note. However I don't think that you
should necessarily write off the idea that this plain formatted ASCII
document could be generated from some form of higher level, structured
document format.

Take a look at the Linux HOWTO stuff - it is exactly what you
want. Getting started, basic installation stuff that you need to read
before you start out with Linux (for example, the Installation-HOWTO,
Hardware-HOWTO, SCSI-HOWTO, PCI-HOWTO, etc). I've used this stuff, and
I used it by getting the ASCII text and sending it straight to a line
printer. This ASCII documentation is developed using a set of simple
tools which also, at no extra effort, allow the generation of the
pretty typeset versions of the manual, the various forms of online
hypertext, etc and also imposes a common format on all the documents,
despite the fact that they are produced and maintained by different
authors.

If we were to copy this sort of approach it would be easier to get it
right from the start, rather than retro-fitting it later (although if
someone provides plain ASCII text then it shouldn't be too hard to put
in the SGML markup tags later).

I haven't tackled the RiscBSD installation yet - I'm still waiting for
my VRAM to turn up. I therefore have a vested interest putting
together some good installation instructions. I'll also have a real
opportunity to try out the procedure in anger in a short while. I
don't have an existing setup that I'm protective of or need to backup
so I can try the installation over and over again, starting with a
clean slate.

If no one else wants the job, or has grounds to feel that they have
prior claim to it, I'd be prepared to have a first stab some
installation instructions, including having a go with the Linux
Documentation Project SGML stuff to prove the idea (and find any
pitfalls that I didn't notice during my cursory inspection of it last
night :-).

What do people think? One caveat that might undermine my suitability
for the job - I'm going away on holiday next week for a couple of
weeks, so it would be towards the end of the month before I started
making any visible progress.

Assuming this proposal is well received, I'd welcome contributions
from anyone who has anything to say about the existing installation
documentation (I have the 1.1-Beta "install.txt" file, dated 8th
February (assuming that the RCS $Id$ tag can be trusted)), any notes
of their own or feedback from their own installation experiences.

Regards,

+-------------------------------------------------------------------------+
Neil Hoggarth                                 Departmental Computer Officer
<neil.hoggarth@physiol.ox.ac.uk>                   Laboratory of Physiology
http://www.physiol.ox.ac.uk/~njh/                     Oxford University, UK
+-------------------------------------------------------------------------+