Hey guys. I've got some more movin' and shakin' ideas to improve how we
do the handbooks. This stems from a recent conversation I had with
robbat2 on how git could be used instead of CVS. No, I'm not proposing
that. That's another topic altogether. :)
As you know, we maintain two handbooks:
networked: /doc/$LANG/handbook/
networkless: /doc/$LANG/handbook/$RELEASE/
None of us are entirely happy about the counterintuitive naming, so I
have a suggestion that will:
1. give our handbooks better names
2. improve the archives
3. *greatly* ease the development of new handbooks at release time
My proposal is this:
networked: /doc/$LANG/handbook/$RELEASE-net/
networkless: /doc/$LANG/handbook/$RELEASE-nonet/
How does this help?
1. It's obvious which handbook is for what, and it retains the release name.
2. Now we can archive the networked handbook, which is appropriate as
the old media is still available.
3. No more copying stuff back and forth from draft/ to any other
directory. When it's time for a new release, copy the stuff to the new
$RELEASE-net/ or -nonet/ directory. Add a single draft disclaimer to the
appropriate TOC, and you're done. At release time remove the disclaimer
and add one to the previous handbooks, making sure to now link the
$RELEASE-foo/ in the index.
Speaking of index, right now index.xml is in handbook/ . With the
proposed new structure, we still keep it in that TLD. It just points to
various directories anyway.
Included files are another matter. Right now, files in
handbook/$RELEASE/ point one level up, to handbook/included.xml. We
would probably have to put the included content in each dir, one for
$RELEASE-net/ and one for $RELEASE-nonet/. This is because old archived
handbooks need static content; if we were to keep them pointing to
handbook/included.xml, this could be bad.
Plus, it's conceivable that the networked or networkless handbooks might
need different includes, so it makes sense to keep them all in their
same dir. Again, this will help when it comes time to archive them.
To sum up:
handbook/2008.1-net/
handbook/2008.1-nonet/
handbook/2009.0-net/
handbook/2009.0-nonet/
etc.
Thoughts? :)
|
