Re: [gentoo-doc] /etc/conf.d/hwclock and /etc/conf.d/adjkerntz

[Sven Vermeulen <swift@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 3118 bytes --]

On Sep 13, 2011 12:44 AM, "Francisco Blas Izquierdo Riera (klondike)" > El
12/09/11 16:29, Sven Vermeulen escribió:
> > My main concern here is that there will be a place where the number of
> > choices is too big.
> When that happens we can always split the document and create new per
> choice ones, that's what is done with the handbooks for example, true?

That is not something we can do for small guides. The part in the
localization guide on (hw)clock and adjkerntz is just a small fraction of
the guide. If we would support 12 different clock management tools, there is
no point in creating 12 different localization guides just for this purpose.


Yes, documentation-wise we can handle this, but it would become confusing.
That's why I would suggest that we don't automatically include small
deviations (one is still okay) everywhere.

> > Also, you'll risk getting a higher frequency on
> > bug reports on such paragraphs.
> Well I have to disagree with that, less more review documents will have
> less bug reports than many less reviewed ones.

Sorry? Not sure I understand. The bug reports that I'm referring to are
those that ask us to include this and that because in a particular one-off
case it is needed. These bugs are very common. I could start updating all
our docs to include some paragraphs on how this is just a bit different with
SELinux enabled, but that would clutter the documents too much.

> >  Think for instance bootloaders, how
> > would we deal with guides there?
> I think the way we do is ok, I mean having different parts for different
> bootloaders.

In handbooks, yes. But not in guides where the bootloader configuration part
is more of a reference (telling the user that he needs to update his
bootloader) rather than the core subject of the document (as is the case
with handbooks).

When it is a reference, we should try make the paragraph generic enough (so
that we do not need to update it with every screw that is changed) and, if
possible, point the user to a more elaborate document explaining this for
his environment (such as "For more information, consult your architectures'
handbook on chapter ..."). The link would then be to the general handbook
index (where they are all listed).

> > What about making it generic (edit your clock management configuration
> > like, like /etc/conf.d/hwclock on ... )?
> Well this particular case offers the deal that the configuration to
> change is the same (just in different places), the problem with generic
> definitions is that they tend to confuse users, and if we specify a
> single alternative then users of the others will get even more confused.
>

I disagree. If we start up listing the various means, users get confused and
start asking on #gentoo "what to pick". The number of users still unsure
about using an amd64 or x86 stage with a x86_64 processor is a daily subject
on our chat channel. Even the forums often have end-user questions about
graphical drivers (even though they do not have a choice in their particular
case).

Wkr,
  Sven Vermeulen

[-- Attachment #2: Type: text/html, Size: 3367 bytes --]