1 |
On Sep 13, 2011 12:44 AM, "Francisco Blas Izquierdo Riera (klondike)" > El |
2 |
12/09/11 16:29, Sven Vermeulen escribió: |
3 |
> > My main concern here is that there will be a place where the number of |
4 |
> > choices is too big. |
5 |
> When that happens we can always split the document and create new per |
6 |
> choice ones, that's what is done with the handbooks for example, true? |
7 |
|
8 |
That is not something we can do for small guides. The part in the |
9 |
localization guide on (hw)clock and adjkerntz is just a small fraction of |
10 |
the guide. If we would support 12 different clock management tools, there is |
11 |
no point in creating 12 different localization guides just for this purpose. |
12 |
|
13 |
|
14 |
Yes, documentation-wise we can handle this, but it would become confusing. |
15 |
That's why I would suggest that we don't automatically include small |
16 |
deviations (one is still okay) everywhere. |
17 |
|
18 |
> > Also, you'll risk getting a higher frequency on |
19 |
> > bug reports on such paragraphs. |
20 |
> Well I have to disagree with that, less more review documents will have |
21 |
> less bug reports than many less reviewed ones. |
22 |
|
23 |
Sorry? Not sure I understand. The bug reports that I'm referring to are |
24 |
those that ask us to include this and that because in a particular one-off |
25 |
case it is needed. These bugs are very common. I could start updating all |
26 |
our docs to include some paragraphs on how this is just a bit different with |
27 |
SELinux enabled, but that would clutter the documents too much. |
28 |
|
29 |
> > Think for instance bootloaders, how |
30 |
> > would we deal with guides there? |
31 |
> I think the way we do is ok, I mean having different parts for different |
32 |
> bootloaders. |
33 |
|
34 |
In handbooks, yes. But not in guides where the bootloader configuration part |
35 |
is more of a reference (telling the user that he needs to update his |
36 |
bootloader) rather than the core subject of the document (as is the case |
37 |
with handbooks). |
38 |
|
39 |
When it is a reference, we should try make the paragraph generic enough (so |
40 |
that we do not need to update it with every screw that is changed) and, if |
41 |
possible, point the user to a more elaborate document explaining this for |
42 |
his environment (such as "For more information, consult your architectures' |
43 |
handbook on chapter ..."). The link would then be to the general handbook |
44 |
index (where they are all listed). |
45 |
|
46 |
> > What about making it generic (edit your clock management configuration |
47 |
> > like, like /etc/conf.d/hwclock on ... )? |
48 |
> Well this particular case offers the deal that the configuration to |
49 |
> change is the same (just in different places), the problem with generic |
50 |
> definitions is that they tend to confuse users, and if we specify a |
51 |
> single alternative then users of the others will get even more confused. |
52 |
> |
53 |
|
54 |
I disagree. If we start up listing the various means, users get confused and |
55 |
start asking on #gentoo "what to pick". The number of users still unsure |
56 |
about using an amd64 or x86 stage with a x86_64 processor is a daily subject |
57 |
on our chat channel. Even the forums often have end-user questions about |
58 |
graphical drivers (even though they do not have a choice in their particular |
59 |
case). |
60 |
|
61 |
Wkr, |
62 |
Sven Vermeulen |