public inbox for gentoo-dev@lists.gentoo.org
 help / color / mirror / Atom feed
Search results ordered by [date|relevance]  view[summary|nested|Atom feed]
thread overview below | download: 
* [gentoo-dev]  Re: [RFC] Features and documentation
  @ 2007-11-30 10:42 99%     ` Steve Long
  0 siblings, 0 replies; 1+ results
From: Steve Long @ 2007-11-30 10:42 UTC (permalink / raw
  To: gentoo-dev

Duncan wrote:
> "Marijn Schouten (hkBst)" <hkBst@gentoo.org> posted
> 474D53CA.7060101@gentoo.org, 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.


-- 
gentoo-dev@gentoo.org mailing list



^ permalink raw reply	[relevance 99%]

Results 1-1 of 1 | reverse | options above
-- pct% links below jump to the message on this page, permalinks otherwise --
2007-11-27 19:21     [gentoo-dev] [RFC] Features and documentation Donnie Berkholz
2007-11-28 11:40     ` Marijn Schouten (hkBst)
2007-11-28 12:38       ` [gentoo-dev] " Duncan
2007-11-30 10:42 99%     ` Steve Long

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox