1 |
Duncan wrote: |
2 |
> "Marijn Schouten (hkBst)" <hkBst@g.o> posted |
3 |
> 474D53CA.7060101@g.o, excerpted below, on Wed, 28 Nov 2007 |
4 |
> 12:40:58 +0100: |
5 |
> |
6 |
>> Donnie Berkholz wrote: |
7 |
>>> How the recent changes happened to allow USE flag descriptions in |
8 |
>>> metadata.xml (which I'm not taking any position on now) gave me an |
9 |
>>> idea. The Linux kernel requires that any needed documentation accompany |
10 |
>>> all changes requiring said documentation -- part of the source-code |
11 |
>>> patch must apply to the Documentation/ directory. Should we require |
12 |
>>> that before you commit any changes, you (or someone) write the |
13 |
>>> documentation for them and commit it or submit a patch at the same |
14 |
>>> time? |
15 |
>> |
16 |
>> We're not talking about ebuilds here, are we? So what ARE we talking |
17 |
>> about? |
18 |
> |
19 |
> Agreed with hkBst and Ciaranm on this one. |
20 |
<snip> |
21 |
> It's kinda hard to discuss such a proposal without knowing where it is |
22 |
> going to be applied, or to read such discussion without being sure |
23 |
> everybody has the same target in mind (maybe it was discussed on IRC and |
24 |
> since I don't normally do that I missed it... seems I'm not the only one, |
25 |
> tho), and what it may be. |
26 |
> |
27 |
I took it to mean anything which changes something already documented on a |
28 |
gentoo doc website (including the devmanual but not individual dev space) |
29 |
or in a man page. That isn't so hard to define, while covering all the |
30 |
changes users or devs need to know about. One would hope devs would be |
31 |
aware of the docs relevant to the software they're changing, so I don't see |
32 |
that as onerous. |
33 |
|
34 |
Additions would count too; I'd imagine someone adding a new feature would |
35 |
want others to know about it. In that regard, asking them to talk to the |
36 |
doc team before it gets committed makes sense; often that process helps |
37 |
development. In the case of core software, or larger projects it might make |
38 |
sense for a point of contact in the doc team (although portage manpages |
39 |
seem to be updated pretty frequently.) |
40 |
|
41 |
While not privy to the prior (if any) discussion, I saw it as an attempt to |
42 |
make the development team aware of documentation responsibility, and asking |
43 |
them to bear that in mind when they change or add stuff (which we want them |
44 |
to do as that's how stuff improves) helps them to become more useful devs, |
45 |
imo. It doesn't have to mean sanctions at any point, but rather that |
46 |
someone would be put in touch with docs if they needed help to document |
47 |
stuff. I'd think new people would welcome that. |
48 |
|
49 |
|
50 |
-- |
51 |
gentoo-dev@g.o mailing list |