| 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 |
Archives