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