Gentoo Archives: gentoo-dev

From: Steve Long <slong@××××××××××××××××××.uk>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] Re: [RFC] Features and documentation
Date: Fri, 30 Nov 2007 10:40:32
Message-Id: fiop46$9o$
In Reply to: [gentoo-dev] Re: [RFC] Features and documentation by Duncan <>
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.
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.)
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.
50 --
51 gentoo-dev@g.o mailing list


Subject Author
[gentoo-dev] Re: [RFC] Features and documentation Duncan <1i5t5.duncan@×××.net>