On Tue 02 Jul, Mark Brinicombe wrote:
 
> A significant code freeze is upon us though. NetBSD 1.2 is in a code freeze
> position at the moment

That sounds like a good opportunity to update the docs, then!

> Perhaps we need to organise a group to work on documentation.
> As well as a new install guide we could do with guides other parts of RiscBSD
> e.g. X, networking, building kernels etc.
> 
> Any thoughts anyone ?
> 

Were it not for the the looming presence of a slight career crisis point due
over the next couple of months (which could put a serious crimp in (a) my spare
time and (b) my access to the net) I wouldn't mind having a go at a 'getting
started' guide.  Main obstacle is my Morley SCSI card which means that 1. I
can't test SCSI installations and 2. I can't access my SCSI CD-ROM drive from
RISCBSD.
 
However - I agree that documentation should be a collaborative effort.  Some
contribution from the kernel team is essential though as they are the ones
who know the 'big picture'.

My experience was that the hardest part of getting RISCBSD going was working
out what I had to download, what the latest version of ??? was and getting it
all downloaded via an Arc with an FTP program which kept barfing on long file
names!  I was thrown a couple of times by out-of-date, contradictory readme
files, and wasted some time downloading sets which turned out not to be what
I thought they were!

So, I really think the first step is a spring-clean of the FTP area (which I
assume is also roughly what you get on the CD).  Obviously this is a
prerequisite to (at least part of) any installation guide.

Here are my suggestions (which people may or may not agree with).  Please
accept them as 'constructive' - I always find it very hard 'complaining' about
freeware products which reperesent such an immense investment in time by the
authors.
 

* There should be
a distinct "1.2 release" directory which is frozen along with the release.
This should contain 1.2, all of 1.2 and nothing but 1.2; one version
(and only one version) of everything (except where there are different versions
for different hardware), no patches, no obsolete files, no 'upload' area.
Everything here should be mutually compatible (to the best of the team's
knowledge).

* Patches, contributions, new/alternative kernels, pre-releases should be kept
in a seperate tree.

* Within the distribution directory there should be a "required" directory,
which contained the RISC-OS bootstrap apps, installation/boot disc utilities
and the 'REQ' sets.  This should also contain any 'getting started'
documentation. Ideally, space permitting, there should be a TARred or GZipped
version of the whole 'required' tree.  Downloading this should give you
everything needed to get a minimal system up and running.

* Next should come "recomm" and "optional" directories - basically containing
the REC and OPT sets.

* I'd also put seperate "Xrequired", "Xrecomm" and "Xopt" directories
containing the X-window stuff.

* There should be one 00README-type file at the top level, which summarised
what RISCBSD was, what hardware the current release supported, and what you
needed to do to proceed.

* Each sub-directory should contain a Readme/Contents/.message (whatever)
file which contained a one-line summary of what each file was (for people
who don't know what a xtzsh or a gnarff is).

* My own preference is to make all filenames RISC-OS and DOS friendly for the
benefit of people who have to transfer files via another machine. 
  
-----------------------------------------------------------------------------
Daniel Pead --- Shell Centre for Maths Education --- University of Nottingham
-----------------------------------------------------------------------------
http://acorn.educ.nottingham.ac.uk/ShellCent/Staff/dan.html
mailto:Daniel.Pead@Nottingham.ac.uk   phoneup:0115 951 4991