Creating an Admin Handbook

[Simon L. Nielsen]

On 2004.07.19 10:03:54 +0000, Murray Stokely wrote:
> I think the time has come to split up the Handbook.  It has grown
> unchecked for far too long and it has been several years since we last
> moved chapters out of the Handbook (and into the Developers Handbook
> in that case).

Without having looked closely into which parts go where, I think it
makes sense to do a split.

> I can perform all of this work, ask for the repo copies, update all
> cross links between chapters to use new entities to link between
> volumes, and update the prefaces and frontmatter for both volumes.  I
> can do this in a single day so as to minimize disruption for others
> working on the Handbook(s).

I would suggest announcing the change a bit in advance and the doing a
freeze for commits to the handbook during the change, to avoid making it
more difficualt than necessary.

> The preface and frontmatter of the
> index.html at www.freebsd.org/handbook would contain a prominent
> pointer to the new volume so that people looking for content can still
> find it easily.

Since a lot of people expect just to look in the "Handbook" and people
have have direct links into to it, I think the notice of the change
should be published so as many people as possible get the heads up.
Perhaps even on announce at .

Since there exist quite a lot of links directly into the Handbook, I
think it would be a good idea to create dummy HTML files, for the
section that's going to be moved.  They would tell people that the
Handbook has been split, and refresh after 10 seconds to the new page,
instead of giving people a 404 error.  I think it should be fairly
trivial to auto generate those HTML files.  It would require doing
something special with for the build dir on www.FreeBSD.org, but I think
it's worth it to avoid confusing users with dead links.

-- 
Simon L. Nielsen
FreeBSD Documentation Team
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20040719/94a1b703/attachment.sig>