Re: [gentoo-dev] Concerns about the new install guide

[Ed Grimm]

On Thu, 4 Mar 2004, Donnie Berkholz wrote:

> On Thu, 2004-03-04 at 03:41, Sven Vermeulen wrote:
>> *And* I'm also tired of developing ways to present documentation than to
>> write documentation. The last few months we've had almost everything: XML
>> changes, XML checking, syntax changes, PDF generation, stylesheet changes,
>> one-page viewing, ... but hardly any new documents. I therefore decided not
>> to work on this "metadata" anymore (personally - not GDP-global) but only
>> write up documents.

Great.  Without quality content, presentation is useless.

I believe that anything the people interested in presentation come up
with at this point will probably be able to be inserted fairly
painlessly into the existing documentation, and I don't expect that
they'll be 100% ready to do anything for a while.  Until they are, I
would think you should be able to focus on the content, and stick with
the presentation method you're using currently.

> You may not consider this a priority, but pretty much everybody else
> does. Fortunately some of these people are on the docs team. =)
>
> Presentation is one of the most crucial things.

Agreed.  Without decent presentation, the documentation is useless.

When I first installed gentoo in early February, I managed to miss the
step of actually mounting the root partition, not because I'm new to
Linux, but because I was trying to follow the guide, and the
instructions to mount / were at the bottom of the page, after a long
list of 'how to partition for system foo', and I was not yet used to
clicking on the 'now countinue with topic' links.

What I would like is a way to compress the docs down to my architecture
and my install style.  I don't want to be distracted by what I'd do if I
were to be installing Gentoo via another method after I've selected my
install method.  On the other hand, it's useful to have that information
available when selecting the install method.  I believe another
compression that would be useful would be based on experience, with the
categories of 'novice, beginner, and expert', where novice is the full
detail you have now, beginner assumes one is familiar with Linux, but
not necessarily Gentoo, and expert compresses out all the explanation,
and simply provides a deployment script.  Actually, as I'm thinking
about it, one might want to add one more, which would produce the
quickstart guide (which I would imagine would be mostly like expert, but
with a little explanation added on.).

This basically suggests three different sets of case-statement-ish
constructs, one for architecture, one for install method, and one for
experience.  If someone doesn't select an axis, the portion of affected
docs look basically the way they do now.

Note that I have no idea how one would do a case statement in XML.


Incidentally, some may say that I'm pandering to both sides of this
dispute.  I'm not.  I'm speaking for balance.  We have two seemingly
competing tasks, which are both required to produce a quality product.
I've spoken more about the presentation, because I think that
presentation currently has the bigger problem.  I understand that there
has recently been a very major effort on the presentation side, but this
was, as far as I can tell, primarily performed with regards to its
impact on the overall content side, without sufficient understanding of
the presentation side.  As it happens, the end result is something that
I believe can be tweaked just a bit to bring the presentation side in
line as well.

Ed

--
gentoo-dev@g.o mailing list