Mailing List Archive: Handbook restructuring proposal

Handbook restructuring proposal

May 2, 2008, 1:01 PM

Post #1 of 6 (2942 views)

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? :)

Re: Handbook restructuring proposal [ In reply to ]

1i5t5.duncan at cox

May 2, 2008, 6:59 PM

Post #2 of 6 (2848 views)

Permalink

Josh Saddler <nightmorph@gentoo.org> posted 481B730A.5090904@gentoo.org,
excerpted below, on Fri, 02 May 2008 13:01:14 -0700:

> 1. It's obvious which handbook is for what, and it retains the release
> name.

This is something that had bugged me for quite awhile. Trying to help
when people refer to "the handbook" is made needlessly complicated, due
to having to try to figure out /which/ handbook, and the confusion if
people aren't referring to the same one.

So ++ from this user! =8^)

I'd still prefer merging them to the same "handbook" URL, tho, with
separate parts for networked and networkless installation. It would then
be clear that the other parts (Working with Portage, etc) are the same
and in general eliminate the possibility of folks seeing only one and
believing that's the "mainline" method of installation, even if they do
see the mention of and link to the other.

--
Duncan - List replies preferred. No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master." Richard Stallman

--
gentoo-doc@lists.gentoo.org mailing list

Re: Re: Handbook restructuring proposal [ In reply to ]

wireless at tampabay

May 3, 2008, 7:57 AM

Post #3 of 6 (2844 views)

Permalink

Duncan wrote:
> Josh Saddler <nightmorph@gentoo.org> posted 481B730A.5090904@gentoo.org,
> excerpted below, on Fri, 02 May 2008 13:01:14 -0700:
>
>> 1. It's obvious which handbook is for what, and it retains the release
>> name.
>
> This is something that had bugged me for quite awhile. Trying to help
> when people refer to "the handbook" is made needlessly complicated, due
> to having to try to figure out /which/ handbook, and the confusion if
> people aren't referring to the same one.
>
> So ++ from this user! =8^)
>
> I'd still prefer merging them to the same "handbook" URL, tho, with
> separate parts for networked and networkless installation. It would then
> be clear that the other parts (Working with Portage, etc) are the same
> and in general eliminate the possibility of folks seeing only one and
> believing that's the "mainline" method of installation, even if they do
> see the mention of and link to the other.
>

This sounds very reasonable. Maybe just one handbook, with a button on
each page that is "silk-screened" with the current architecture one is
reading about. If one wants to switch from the ppc version to the
amd64, just put your mouse over these silk-screen and a popup appears
where they can switch to another architecture.

If, for what ever reason we need to have multiple revisions of the
handbook (say 2007.0, 2008.0 2008.1) for example, then the version
number could also be an option in the popup menu. If you want to keep
an old versions of the handbook around, for whatever reason, but
you do not want folks to really use them, then use a pastel
(background) water-mark that used a meaningful keyword, such as
"deprecated" or such. The popup could be replace with any of a varity
of functionally equivalent interface buttons. The ideas is one
document with a button to make switching between architectures,
revisions, and such, a singular function. Then when somebody refers to
the handbook, they can site the section number and the arch (which is
usually understood, and possible the revision number.

These are only ideas, nothing that I'm hardened on as ideas. However,
consolidation of documents into a minimalistic form is good for
everyone, methinks.

James
--
gentoo-doc@lists.gentoo.org mailing list

Re: Handbook restructuring proposal [ In reply to ]

swift at gentoo

May 3, 2008, 9:15 AM

Post #4 of 6 (2854 views)

Permalink

On 5/2/08, Josh Saddler <nightmorph@gentoo.org> wrote:
[...]
> My proposal is this:
> networked: /doc/$LANG/handbook/$RELEASE-net/
> networkless: /doc/$LANG/handbook/$RELEASE-nonet/

I understand that it allows the networked to be prepared for future
changes (like upcoming openrc stuff), but chances are that openrc
becomes stable at a different point in time than a specific release.
At that point, we'll need the networked handbooks to be updated.

For this reason, I don't support putting the release inside the
networked handbook URL. If anything, I would be glad to call it
handbook/current or handbook/networked but without any release
reference.

Wkr,
Sven Vermeulen
--
gentoo-doc@lists.gentoo.org mailing list

Re: Handbook restructuring proposal [ In reply to ]

wolf31o2 at gentoo

May 7, 2008, 12:02 AM

Post #5 of 6 (2847 views)

Permalink

On Sat, 2008-05-03 at 18:15 +0200, Sven Vermeulen wrote:
> I understand that it allows the networked to be prepared for future
> changes (like upcoming openrc stuff), but chances are that openrc
> becomes stable at a different point in time than a specific release.

Actually, we asked specifically for this to be held until 2008.1, since
it won't be ready in time for 2008.0, so this is actually one major
change that will coincide with a release.

--
Chris Gianelloni
Release Engineering Strategic Lead
Games Developer

Re: Handbook restructuring proposal [ In reply to ]

vapier at gentoo

May 7, 2008, 1:17 AM

Post #6 of 6 (2840 views)

Permalink

On Wednesday 07 May 2008, Chris Gianelloni wrote:
> On Sat, 2008-05-03 at 18:15 +0200, Sven Vermeulen wrote:
> > I understand that it allows the networked to be prepared for future
> > changes (like upcoming openrc stuff), but chances are that openrc
> > becomes stable at a different point in time than a specific release.
>
> Actually, we asked specifically for this to be held until 2008.1, since
> it won't be ready in time for 2008.0, so this is actually one major
> change that will coincide with a release.

and openrc isnt even close to release onto stable. we've broken enough
unstable boxes as it is.
-mike

Mailing List Archive

Attached Files:

Attached Files:

Attached Files: