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