Gentoo Logo
Gentoo Spaceship

Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-doc
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
To: gentoo-doc@g.o
From: Sven Vermeulen <swift@g.o>
Subject: Re: /etc/conf.d/hwclock and /etc/conf.d/adjkerntz
Date: Tue, 13 Sep 2011 14:11:19 +0200
<p>On Sep 13, 2011 12:44 AM, &quot;Francisco Blas Izquierdo Riera (klondike)&quot; &gt; El 12/09/11 16:29, Sven Vermeulen escribió:<br>
&gt; &gt; My main concern here is that there will be a place where the number of<br>
&gt; &gt; choices is too big.<br>
&gt; When that happens we can always split the document and create new per<br>
&gt; choice ones, that&#39;s what is done with the handbooks for example, true?</p>
<p>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. </p>

<p>Yes, documentation-wise we can handle this, but it would become confusing. That&#39;s why I would suggest that we don&#39;t automatically include small deviations (one is still okay) everywhere.</p>
<p>&gt; &gt; Also, you&#39;ll risk getting a higher frequency on<br>
&gt; &gt; bug reports on such paragraphs.<br>
&gt; Well I have to disagree with that, less more review documents will have<br>
&gt; less bug reports than many less reviewed ones.</p>
<p>Sorry? Not sure I understand. The bug reports that I&#39;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.</p>

<p>&gt; &gt;  Think for instance bootloaders, how<br>
&gt; &gt; would we deal with guides there?<br>
&gt; I think the way we do is ok, I mean having different parts for different<br>
&gt; bootloaders.</p>
<p>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).</p>

<p>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 &quot;For more information, consult your architectures&#39; handbook on chapter ...&quot;). The link would then be to the general handbook index (where they are all listed).</p>

<p>&gt; &gt; What about making it generic (edit your clock management configuration<br>
&gt; &gt; like, like /etc/conf.d/hwclock on ... )?<br>
&gt; Well this particular case offers the deal that the configuration to<br>
&gt; change is the same (just in different places), the problem with generic<br>
&gt; definitions is that they tend to confuse users, and if we specify a<br>
&gt; single alternative then users of the others will get even more confused.<br>
<p>I disagree. If we start up listing the various means, users get confused and start asking on #gentoo &quot;what to pick&quot;. 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).</p>

  Sven Vermeulen</p>
/etc/conf.d/hwclock and /etc/conf.d/adjkerntz
-- Francisco Blas Izquierdo Riera (klondike)
Re: /etc/conf.d/hwclock and /etc/conf.d/adjkerntz
-- Sven Vermeulen
Re: /etc/conf.d/hwclock and /etc/conf.d/adjkerntz
-- Francisco Blas Izquierdo Riera (klondike)
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
Re: /etc/conf.d/hwclock and /etc/conf.d/adjkerntz
Next by thread:
OpenRC tracker "empty"
Previous by date:
Re: /etc/conf.d/hwclock and /etc/conf.d/adjkerntz
Next by date:
OpenRC tracker "empty"

Updated Apr 08, 2012

Summary: Archive of the gentoo-doc mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.