Mailing List Archive

On Mon, Sep 12, 2011 at 12:26 AM, Francisco Blas Izquierdo Riera
(klondike) <klondike@gentoo.org> wrote:
> Well what I want to ask here is how should we aproach this. As things stand
> now:
> The open rc upgrade guide mentions both (which is ok)
> The gentoo bsd guide just refers to adjkerntz (which is ok)
> The hand book refers only to hwclock (which is "ok" as long as there doesn't
> appears a gentoo-bsd handbook).
> Tthe localization guide still refers to the older clock one, here I'd like
> to say:
>
> If,
> for some reason, you need your hardware clock not to be in UTC,
> you will need to edit <path>/etc/conf.d/hwclock</path> (or if you
> use Gentoo BSD <path>/etc/conf.d/hwclock</path> and change
> the value of <c>clock</c> from <c>UTC</c> to <c>local</c>.

My main concern here is that there will be a place where the number of
choices is too big. Also, you'll risk getting a higher frequency on
bug reports on such paragraphs. Think for instance bootloaders, how
would we deal with guides there? I'm sure we do not want to generate
separate guides for just all this sort of stuff (and then use
keywords)...

What about making it generic (edit your clock management configuration
like, like /etc/conf.d/hwclock on ... )?

Wkr,
Sven Vermeulen

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?
> 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.
> 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.
> I'm sure we do not want to generate
> separate guides for just all this sort of stuff (and then use
> keywords)...
We don't.
> 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.

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