From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from pigeon.gentoo.org ([208.92.234.80] helo=lists.gentoo.org) by finch.gentoo.org with esmtp (Exim 4.60) (envelope-from ) id 1R3Rq3-0004Ud-KL for garchives@archives.gentoo.org; Tue, 13 Sep 2011 12:11:44 +0000 Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id B948421C187; Tue, 13 Sep 2011 12:11:31 +0000 (UTC) Received: from mail-yx0-f181.google.com (mail-yx0-f181.google.com [209.85.213.181]) by pigeon.gentoo.org (Postfix) with ESMTP id 7D95521C022 for ; Tue, 13 Sep 2011 12:11:21 +0000 (UTC) Received: by yxk30 with SMTP id 30so476712yxk.40 for ; Tue, 13 Sep 2011 05:11:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:content-type; bh=2ir8wRD2VBZvKSPi1IWhhGg0vmjN1kQ07jKXgSVsv/4=; b=FFbT8ys4f0+dS30/1y70ufrHEN82nGRXTgCtaWCkFwEn3QSbN67gKDcF21yckIJsNg X8cWzSaMYY2cptd29Ded4BWJNddpCwG148NTTcHth/bBSrNvDBXbJ/3eG7K2sBqVbUwK sNkJ9IbpnfV+/XhPbJoqrq2FhgpND8t+JrF90= Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-doc@lists.gentoo.org Reply-to: gentoo-doc@lists.gentoo.org MIME-Version: 1.0 Received: by 10.42.131.71 with SMTP id y7mr1708645ics.315.1315915880798; Tue, 13 Sep 2011 05:11:20 -0700 (PDT) Sender: sven.j.vermeulen@gmail.com Received: by 10.231.170.82 with HTTP; Tue, 13 Sep 2011 05:11:19 -0700 (PDT) Received: by 10.231.170.82 with HTTP; Tue, 13 Sep 2011 05:11:19 -0700 (PDT) In-Reply-To: <4E6E8ABB.5050909@gentoo.org> References: <4E6D35A3.5020005@gentoo.org> <4E6E8ABB.5050909@gentoo.org> Date: Tue, 13 Sep 2011 14:11:19 +0200 X-Google-Sender-Auth: VZ4c4HZnEFIzYkupSYXb6fgWzzE Message-ID: Subject: Re: [gentoo-doc] /etc/conf.d/hwclock and /etc/conf.d/adjkerntz From: Sven Vermeulen To: gentoo-doc@lists.gentoo.org Content-Type: multipart/alternative; boundary=90e6ba212173a11b5c04acd18a0c X-Archives-Salt: X-Archives-Hash: eec7164995ee4ec482ccfe4900ddb30f --90e6ba212173a11b5c04acd18a0c Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On Sep 13, 2011 12:44 AM, "Francisco Blas Izquierdo Riera (klondike)" > El 12/09/11 16:29, Sven Vermeulen escribi=F3: > > 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 i= s 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 wit= h 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 par= t 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 an= d 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 subjec= t 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 particula= r case). Wkr, Sven Vermeulen --90e6ba212173a11b5c04acd18a0c Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable

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

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

Yes, documentation-wise we can handle this, but it would become confusin= g. That's why I would suggest that we don't automatically include s= mall 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 hav= e
> 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 a= ll 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.

> > =A0Think for instance bootloaders, how
> > would we deal with guides there?
> I think the way we do is ok, I mean having different parts for differe= nt
> 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 b= ootloader) rather than the core subject of the document (as is the case wit= h 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 f= or his environment (such as "For more information, consult your archit= ectures' 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 confi= guration
> > 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 generi= c
> definitions is that they tend to confuse users, and if we specify a > single alternative then users of the others will get even more confuse= d.
>

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 que= stions about graphical drivers (even though they do not have a choice in th= eir particular case).

Wkr,
=A0 Sven Vermeulen

--90e6ba212173a11b5c04acd18a0c--