I recently put a VAX together and noticed -- it can't be helped -- that
the docs are out of date and sometimes misleading.  I can fix this, and
I'd rather do it before I've forgotten or lost interest.  I want to list
some specific issues, so you can see what I'm talking about (and so I
don't lose track); then I'd like to ask how best to remedy them.  

To begin, http://www.netbsd.org/Documentation/network/netboot/mop.html
says:

"First, you need to get a copy of the bootloader. This can be found in the
NetBSD 1.5.3 distribution as:
ftp://ftp.netbsd.org/pub/NetBSD/NetBSD-1.5.3/vax/installation/netboot/netbsd.ram.gz"

I didn't know what that file was used for.  The document doesn't say.  I
found a different file, install.ram.gz, which I eventually intuited is the
install kernel.  

http://www.netbsd.org/Documentation/network/netboot/bootpd.html includes:

#/etc/bootptab
client.test.net:\
        :ht=ether:\
        :ha=CCCCCCCCCCCC:\
        :sm=255.255.255.0:\
        :lg=192.168.1.5:\
        :ip=192.168.1.10:\
        :hn:\
        :bf=[/tftpboot/]boot.netbsd:\   # see note below
        :bs=auto:\
        :rp=/export/client/root/:\
        :vm=auto:                       # see note below for next hardware
        :vm=rfc1048:                    # see note below for alpha
hardware

There's no indication what "CCCCCCCCCCCC" means.  Too, I had to read the
bootptab man page to know that "[/tftpboot/]" means "this part is
optional, depending".  I think a clearer typography would use italics for
placeholders and/or boldface for constants, as jade renders sgml.  

Another point of confusion, at least for me, was that 
http://www.netbsd.org/Documentation/network/netboot/tftpd.html 

says, "Next, you should copy all of the files necessary for your
architecture to /tftpboot, as specified in the client
architecture-specific introduction" but 
http://www.netbsd.org/Documentation/network/netboot/intro.vax.html 

doesn't mention what to put in /tftpboot (although it's very helpful with
the VAX firmware).  Also, at the bottom of that page is a short list of
links to the rest of the steps, which I found helpful.  But that list is
missing a link to the tftp setup.  

I also got into trouble reading Brian Chase's VAX-netboot-HOWTO.html. 
That document, to which I was frequently referred, is now 5 years old, and
almost all the specifics have been superseded.  Maybe others are more
savvy, but had to keep remembering *not* to read it, once I realized it
was a dead end.  The newcomer will be misled; the old hand can appreciate
the art.  No criticism intended to Brian, I hope that's clear.  

On the plus side, once I got to NFS, it was pretty much clear sailing. 
Prior to the VAX, my whole NFS experience had consisted of one Sun
workstation netboot installation.  But the NFS steps are very clear, so my
lack of NFS experience wasn't much of an impediment.  In fact, I wound up
with a complete diskless installation because I overlooked the link to
netboot/local.install.html on netboot/nfs.html.  <shrug>  

I also want to criticise vax/INSTALL.html.  

1.  Are there really any vaxen with pcmcia cards? IDE disks?   
2.  "You will be asked if you want to use the entire disk or only part of
the disk."
3.  "To do the upgrade, you must have the boot floppy available."
4.  "partition sizes for a full install ... /usr 110 MB".

#4 May be true, but somewhere it should mention that for ftp
#installations, sysinst pulls all the sets and then starts installing.  My
#200 MB boot LXT-213S ran out of room using ftp; I put the sets on the NFS
#server to complete the installation.  

For me, what vax/INSTALL.html lacked was a concise recap of what's
happening, something to serve as a VAX-specific guide to the netboot
process.  Something like:

Service	 Provides		Filename on server
-------	 --------------------	-------------------------
mopd	 bootloader [url]	/tftpboot/mop/MOPBOOT.SYS
bootpd	 ip address, hostname,	/etc/bootptab
	 boot loader filename
tftpd	 bootloader [url]	/tftpboot/vax/1.6/boot
nfs	 install kernel [url]	/export/vax/root/netbsd 

If each Service were linked back to its netboot page and each Provides
were linked to the file on ftp.netbsd.org, it would be simpler to navigate
and get the right stuff.  It would also be unnecessary to keep updating
links in the netboot pages; they could instead refer to bookmarks in
INSTALL.html.  

Finally, I should mention there's no errata or readme to point out:

1.  The NetBSD 1.5 mopd is broken.
2.  The only working MOP bootload is 1.5.3.  Not prior, not since.  

At the very least, there should be a readme that says no one's maintaining
the readme, referring the reader to the ML archives.  

Sorry for the long list.  You only do something once for the first time. 
Soon it becomes obvious what to do, and by then it's too late to see where
the newcomer can go astray.  In that sense, I'm still ignorant enough to
be useful.  

+++

I've seen messages in the archives indicating a move toward sgml/docbook,
with which I'm familiar.  Does the netboot document want conversion to
sgml?  I know how to do that.  

I can also update the existing docs in html, per the above remarks.  You
want diffs against current cvs, new files, what?  You want to stick with
<i> and <tt> or move to <em> and <kbd>?  

--jkl