[gentoo-dev] [RFC] Features and documentation

[gentoo-dev] [RFC] Features and documentation

[Donnie Berkholz]

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?

To sum up: No undocumented changes.

Discuss.

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 166 bytes --]

On Tue, 27 Nov 2007 11:21:44 -0800
Donnie Berkholz <dberkholz@gentoo.org> wrote:
> To sum up: No undocumented changes.

Define 'change'.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] [RFC] Features and documentation

[Doug Klima]

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?
>
> To sum up: No undocumented changes.
>
> Discuss.
>
> Thanks,
> Donnie
>   
I agree that documentation should be provided before anything is committed.

I'd also like to note that documentation was provided with the USE flag
descriptions as well as an example metadata.xml with all the new
features being used was provided.

--
Doug Klima
Gentoo Developer
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Donnie Berkholz]

On 19:25 Tue 27 Nov     , Ciaran McCreesh wrote:
> On Tue, 27 Nov 2007 11:21:44 -0800
> Donnie Berkholz <dberkholz@gentoo.org> wrote:
> > To sum up: No undocumented changes.
> 
> Define 'change'.

That was the summary, so you should be able to get the information you 
want from the paragraph above it.

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 529 bytes --]

On Tue, 27 Nov 2007 11:36:17 -0800
Donnie Berkholz <dberkholz@gentoo.org> wrote:
> On 19:25 Tue 27 Nov     , Ciaran McCreesh wrote:
> > On Tue, 27 Nov 2007 11:21:44 -0800
> > Donnie Berkholz <dberkholz@gentoo.org> wrote:
> > > To sum up: No undocumented changes.
> > 
> > Define 'change'.
> 
> That was the summary, so you should be able to get the information
> you want from the paragraph above it.

But I can't, hence why I asked. You haven't at any point said what you
mean by 'change'.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] [RFC] Features and documentation

[Alec Warner]

On 11/27/07, Donnie Berkholz <dberkholz@gentoo.org> 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?
>
> To sum up: No undocumented changes.

No, because this is not a realistic requirement, it's an ideal case.
People will just commit changes without documentation anyway.

>
> Discuss.
>
> Thanks,
> Donnie
> --
> gentoo-dev@gentoo.org mailing list
>
>
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Rémi Cardona]

Alec Warner wrote:
> On 11/27/07, Donnie Berkholz <dberkholz@gentoo.org> 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?
>>
>> To sum up: No undocumented changes.
> 
> No, because this is not a realistic requirement, it's an ideal case.
> People will just commit changes without documentation anyway.

What if Donnie had used s/changes/new features/ ? Then his proposal
makes much more sense.

For bugfix, we already have ChangeLogs.

My 2 euro ¢

Cheers,
Rémi
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Marijn Schouten (hkBst)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

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?

Marijn

- --
Marijn Schouten (hkBst), Gentoo Lisp project, Gentoo ML
<http://www.gentoo.org/proj/en/lisp/>, #gentoo-{lisp,ml} on FreeNode
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.7 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHTVPKp/VmCx0OL2wRAoMqAJ4zkrWMSmthzxNNjc+/syiz4EMq2wCcCnSE
CA8fiI/lq716rIV5+i9r4lI=
=ypdc
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: [RFC] Features and documentation

[Duncan]

"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.

Donnie, I'm sure you have the scope of what you intend to apply this to 
firmly in your mind, but it's not at all clear from your post what it 
is.  Ebuilds?  Doesn't make sense with changelog already there and 
generally used (when folks don't forget or screw the format and therefore 
the parsing thereof).  Eclasses?  OK, that makes more sense, but is that 
what you intended?  Gentoo sponsored projects such as portage?  Isn't 
that stepping on the various project's toes and don't most of them have 
such requirements in place formally or not as it is?  Something else?  
Some combination of the above?

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.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Zhang Le]

Rémi Cardona wrote:
> Alec Warner wrote:
>> On 11/27/07, Donnie Berkholz <dberkholz@gentoo.org> 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?
>>>
>>> To sum up: No undocumented changes.
>> No, because this is not a realistic requirement, it's an ideal case.
>> People will just commit changes without documentation anyway.
> 
> What if Donnie had used s/changes/new features/ ? Then his proposal
> makes much more sense.

I agree that new features makes more sense here. USE flag description in
metadata.xml is just an example of new feature, IMO.

My 2 HK$, ;)

-- 
Zhang Le, Robert
GPG key ID: 1E4E2973
Fingerprint: 0260 C902 B8F8 6506 6586 2B90 BC51 C808 1E4E 2973
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: [RFC] Features and documentation

[Christian Faulhammer]

[-- Attachment #1: Type: text/plain, Size: 601 bytes --]

Donnie Berkholz <dberkholz@gentoo.org>:

> To sum up: No undocumented changes.
> Discuss.

 Would be nice...what we need is a maniac taking care of the devmanual
and merging it with all other development related information shattered
around (and nag people for more information).  But as we aren't able to
publish a GWN regularly (I don't accuse anyone, I know that it is a
hard job), I don't think we get near that goal, soon.

V-Li

-- 
Christian Faulhammer, Gentoo Lisp project
<URL:http://www.gentoo.org/proj/en/lisp/>, #gentoo-lisp on FreeNode

<URL:http://www.faulhammer.org/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: [RFC] Features and documentation

[Donnie Berkholz]

On 12:38 Wed 28 Nov     , Duncan wrote:
> Donnie, I'm sure you have the scope of what you intend to apply this to 
> firmly in your mind, but it's not at all clear from your post what it 
> is.  Ebuilds?  Doesn't make sense with changelog already there and 
> generally used (when folks don't forget or screw the format and therefore 
> the parsing thereof).  Eclasses?  OK, that makes more sense, but is that 
> what you intended?  Gentoo sponsored projects such as portage?  Isn't 
> that stepping on the various project's toes and don't most of them have 
> such requirements in place formally or not as it is?  Something else?  
> Some combination of the above?
> 
> 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.

Many of the replies keep asking for details -- details that don't exist. 
Apply the concept abstractly: things that need to be documented must 
have documentation available in the appropriate form at the time they're 
committed.

Some of these things are already documented fairly well, generally, such 
as changes to single ebuilds and eclasses. Others, such as global 
features, are not always. At this level of change, a GLEP is one form of 
documentation; the handbook or devmanual is another.

What remains unclear about this principle?

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Donnie Berkholz]

On 19:10 Tue 27 Nov     , Alec Warner wrote:
> No, because this is not a realistic requirement, it's an ideal case.
> People will just commit changes without documentation anyway.

Here's my understanding of what you said: Because people will break 
rules and violate standards, we shouldn't have any.

Is that accurate?

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: [RFC] Features and documentation

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 1916 bytes --]

On Wed, 28 Nov 2007 13:14:05 -0800
Donnie Berkholz <dberkholz@gentoo.org> wrote:
> Many of the replies keep asking for details -- details that don't
> exist. Apply the concept abstractly: things that need to be
> documented must have documentation available in the appropriate form
> at the time they're committed.

Which still doesn't bring anything discussable or implementable. A
large part of why many things aren't documented is that people have
very different ideas about what level of documentation is required;
this does nothing to affect that.

> What remains unclear about this principle?

It's entirely nebulous and has nothing that can be discussed or agreed
upon, beyond giving people a feel good "ooh, yes, we should do this"
with no practical purpose. It has an unpleasant smell of something a
Dilbert-esque manager would introduce after having read a "Project
Management for Dummies" book full of slogans and generalities.

So, if you want to take this somewhere useful:

* Decide what the scope of a change is. Are we talking anything
user-visible? Anything substantially user-visible? Anything requiring
user action? Anything developer-visible? Anything requiring developer
action? Anything visible to small numbers of developers working in a
specific area?

* Decide what the appropriate level of documentation is.

* Discuss how you're going to get documentation of a sufficiently high
quality. Most developers aren't going to go out and spend several months
studying technical writing...

* Decide whether it's worth putting the limited available writing
resources into developer documentation that will only be read by a few
hundred people, rather than putting more focus into user documentation
that will be read by pretty much everyone.

You know... Practical things, rather than things that make you feel
good but go nowhere.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Re: [RFC] Features and documentation

[Donnie Berkholz]

On 21:33 Wed 28 Nov     , Ciaran McCreesh wrote:
> On Wed, 28 Nov 2007 13:14:05 -0800
> > What remains unclear about this principle?
> 
> It's entirely nebulous and has nothing that can be discussed or agreed
> upon, beyond giving people a feel good "ooh, yes, we should do this"
> with no practical purpose. It has an unpleasant smell of something a
> Dilbert-esque manager would introduce after having read a "Project
> Management for Dummies" book full of slogans and generalities.
> 
> So, if you want to take this somewhere useful:
> 
> * Decide what the scope of a change is. Are we talking anything
> user-visible? Anything substantially user-visible? Anything requiring
> user action? Anything developer-visible? Anything requiring developer
> action? Anything visible to small numbers of developers working in a
> specific area?
> 
> * Decide what the appropriate level of documentation is.
> 
> * Discuss how you're going to get documentation of a sufficiently high
> quality. Most developers aren't going to go out and spend several months
> studying technical writing...
> 
> * Decide whether it's worth putting the limited available writing
> resources into developer documentation that will only be read by a few
> hundred people, rather than putting more focus into user documentation
> that will be read by pretty much everyone.

I think that in most cases it is self-evident to the developer how much 
documentation is useful, and if the community disagrees with that 
developer, anyone else is welcome to say so. There are always a few 
people out on the edge, but most people realize how much documentation 
should exist. I don't see a benefit to all these precise specifications.

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Alec Warner]

On 11/28/07, Donnie Berkholz <dberkholz@gentoo.org> wrote:
> On 19:10 Tue 27 Nov     , Alec Warner wrote:
> > No, because this is not a realistic requirement, it's an ideal case.
> > People will just commit changes without documentation anyway.
>
> Here's my understanding of what you said: Because people will break
> rules and violate standards, we shouldn't have any.
>
> Is that accurate?
>

Kind of.

Most people follow most rules.  Most people break a subset of rules.

You are essentially adding an unreasonable (in my view) rule that I
expect nearly everyone to break or ignore, thereby adding little or no
value to the project as whole.  Most people care about documentation
in the abstract sense, almost no one cares *enough* to write any ;)

Forcing people to write documentation won't get it written, people
will continue to act like we just saw and either the rule will get
ignored, or someone will change the rule, or people will leave because
the rule is enforced aggressively and it has ruined the ability to
contribute to the project.

This is why I offered to write the GLEP for Diego and Cardoe, because
I know they are not interested in writing it themselves.  Thats why we
have a doc-team that for some sick reason enjoy writing and
maintaining documentation.

-Alec
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Donnie Berkholz]

On 16:43 Wed 28 Nov     , Alec Warner wrote:
> On 11/28/07, Donnie Berkholz <dberkholz@gentoo.org> wrote:
> > Here's my understanding of what you said: Because people will break
> > rules and violate standards, we shouldn't have any.
> >
> > Is that accurate?
> >
> 
> Kind of.
> 
> Most people follow most rules.  Most people break a subset of rules.
> 
> You are essentially adding an unreasonable (in my view) rule that I
> expect nearly everyone to break or ignore, thereby adding little or no
> value to the project as whole.  Most people care about documentation
> in the abstract sense, almost no one cares *enough* to write any ;)
> 
> Forcing people to write documentation won't get it written, people
> will continue to act like we just saw and either the rule will get
> ignored, or someone will change the rule, or people will leave because
> the rule is enforced aggressively and it has ruined the ability to
> contribute to the project.

The Linux kernel seems to still have contributors, despite its 
requirement. It seems like people decide to leave after nearly any 
change Gentoo makes these days, so I'm not even sure how much we should 
consider that unless we want to stop all development and do nothing. 
(But I guess that also would be a change, so people would quit.)

> This is why I offered to write the GLEP for Diego and Cardoe, because
> I know they are not interested in writing it themselves.  Thats why we
> have a doc-team that for some sick reason enjoy writing and
> maintaining documentation.

You've made some great points here about working with people who enjoy 
dealing with docs. What I'm saying is that we should work with these 
people before committing rather than after.

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Alec Warner]

On 11/28/07, Donnie Berkholz <dberkholz@gentoo.org> wrote:
> On 16:43 Wed 28 Nov     , Alec Warner wrote:
> > On 11/28/07, Donnie Berkholz <dberkholz@gentoo.org> wrote:
> > > Here's my understanding of what you said: Because people will break
> > > rules and violate standards, we shouldn't have any.
> > >
> > > Is that accurate?
> > >
> >
> > Kind of.
> >
> > Most people follow most rules.  Most people break a subset of rules.
> >
> > You are essentially adding an unreasonable (in my view) rule that I
> > expect nearly everyone to break or ignore, thereby adding little or no
> > value to the project as whole.  Most people care about documentation
> > in the abstract sense, almost no one cares *enough* to write any ;)
> >
> > Forcing people to write documentation won't get it written, people
> > will continue to act like we just saw and either the rule will get
> > ignored, or someone will change the rule, or people will leave because
> > the rule is enforced aggressively and it has ruined the ability to
> > contribute to the project.
>
> The Linux kernel seems to still have contributors, despite its
> requirement. It seems like people decide to leave after nearly any
> change Gentoo makes these days, so I'm not even sure how much we should
> consider that unless we want to stop all development and do nothing.
> (But I guess that also would be a change, so people would quit.)
>
> > This is why I offered to write the GLEP for Diego and Cardoe, because
> > I know they are not interested in writing it themselves.  Thats why we
> > have a doc-team that for some sick reason enjoy writing and
> > maintaining documentation.
>
> You've made some great points here about working with people who enjoy
> dealing with docs. What I'm saying is that we should work with these
> people before committing rather than after.
>

I can get behind that then ;)

> Thanks,
> Donnie
> --
> gentoo-dev@gentoo.org mailing list
>
>
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: [RFC] Features and documentation

[Duncan]

Ciaran McCreesh <ciaran.mccreesh@blueyonder.co.uk> posted
20071128213319.09f73e89@blueyonder.co.uk, excerpted below, on  Wed, 28 Nov
2007 21:33:19 +0000:

> On Wed, 28 Nov 2007 13:14:05 -0800
> Donnie Berkholz <dberkholz@gentoo.org> wrote:
>> Many of the replies keep asking for details -- details that don't
>> exist. Apply the concept abstractly: things that need to be documented
>> must have documentation available in the appropriate form at the time
>> they're committed.

OK, I can accept that details don't (yet) exist, but that's why the 
discussion.  =8^)  Hopefully it'll flesh out some of these details.

> A large part of why many things aren't documented is that people have
> very different ideas about what level of documentation is required;
> this does nothing to affect that.

Agreed.  The current discussion on the metadata changes is a prime 
example.  Obviously, there was disagreement on the level of documentation 
needed.  A nebulous "document before change" policy can't help in such 
cases, as one side or the other's going to get very frustrated, either by 
"extreme" enforcement (seen by the one side), or lack of enforcement 
(seen by the other).  The /best/ that could come out of such would be 
that it's as if there were no policy at all.  The worst... people leaving 
because of "unfair" enforcement of a policy so nebulous they never saw 
the action coming, or OTOH, because Gentoo refuses to enforce its own 
policies.

>> What remains unclear about this principle?
> 
> It has an unpleasant smell of something a Dilbert-esque manager would
> introduce after having read a "Project Management for Dummies" book
> full of slogans and generalities.

Leave it to ciarnm to be so direct, amusing tho it is, but that pretty 
much nails it.  I've seen it said by some that Gentoo's no longer "fun".  
I disagree but honestly, ask yourself if there's a better way to ruin the 
fun remaining than by instituting policies so nebulous they simply /beg/ 
for argument over their application.  The idea sounds so nice, something 
everybody should be able to agree to in principle, but that's precisely 
the problem, there's no specifics, so no practical way to tell where or 
how it applies, or what changes (if any) it would bring.  Pardon my 
saying so but at least in the US, it's the season of politics, and we're 
seeing a lot of this vague "big stroke" pie in the sky painting right 
now.  Unlike most of those, there's a chance with this one to get it 
nailed down to the point it's actually practical.

(Bullet point suggestions for tightening down the spec to something 
"workable" omitted for brevity.  Ciarnm put them well enough.)

> You know... Practical things, rather than things that make you feel
> good but go nowhere.

=8^)

As an alternative or adjunct to Ciaran's suggestions, perhaps this will 
be easier, tho not immediately as complete.  Self-evidently if you are 
making the proposal, you believe there's a need for it and that it would 
change the outcome in one or more events in the recent and possibly less 
recent past.  What about listing them, and how you see your proposal 
changing the outcome thereof.  At least that would give us some concrete 
examples to apply the policy to in our heads as we discuss it.  As I 
said, it's not as complete as the thorough evaluation Ciaranm proposed, 
but one has to start somewhere, and this would be one way to do it.  
OTOH, it's also getting very specific about perhaps sensitive events, 
while Ciaran's proposal would avoid singling out such events and 
therefore people by name, thus having the advantage there as well as in 
ultimate wholeness, once it's done.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: [RFC] Features and documentation

[Donnie Berkholz]

On 05:04 Thu 29 Nov     , Duncan wrote:
> Leave it to ciarnm to be so direct, amusing tho it is, but that pretty 
> much nails it.  I've seen it said by some that Gentoo's no longer "fun".  
> I disagree but honestly, ask yourself if there's a better way to ruin the 
> fun remaining than by instituting policies so nebulous they simply /beg/ 
> for argument over their application.  The idea sounds so nice, something 
> everybody should be able to agree to in principle, but that's precisely 
> the problem, there's no specifics, so no practical way to tell where or 
> how it applies, or what changes (if any) it would bring.  Pardon my 
> saying so but at least in the US, it's the season of politics, and we're 
> seeing a lot of this vague "big stroke" pie in the sky painting right 
> now.  Unlike most of those, there's a chance with this one to get it 
> nailed down to the point it's actually practical.

In fact, I believe exactly the opposite. What we want to create are 
basic philosophies to guide us. Nailing down a million tiny details is 
what makes things not fun, and what makes them impossible to learn. 
We're not trying to write a specification here, we're trying to come up 
with a set of guidelines that people could actually learn and remember.

Thanks,
Donnie
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: [RFC] Features and documentation

[Christian Faulhammer]

[-- Attachment #1: Type: text/plain, Size: 566 bytes --]

Donnie Berkholz <dberkholz@gentoo.org>:

> The Linux kernel seems to still have contributors, despite its 
> requirement.

 You have been quoted on LWN:
"'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.' -- Donnie Berkholz engages
in some wishful thinking"

V-Li

-- 
Christian Faulhammer, Gentoo Lisp project
<URL:http://www.gentoo.org/proj/en/lisp/>, #gentoo-lisp on FreeNode

<URL:http://www.faulhammer.org/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] [RFC] Features and documentation

[Santiago M. Mola]

On Nov 29, 2007 1:43 AM, Alec Warner <antarus@gentoo.org> wrote:
>
> Forcing people to write documentation won't get it written, people
> will continue to act like we just saw and either the rule will get
> ignored, or someone will change the rule, or people will leave because
> the rule is enforced aggressively and it has ruined the ability to
> contribute to the project.
>
> This is why I offered to write the GLEP for Diego and Cardoe, because
> I know they are not interested in writing it themselves.  Thats why we
> have a doc-team that for some sick reason enjoy writing and
> maintaining documentation.
>

It would be reasonable to require devs to:
a) Document changes before commiting when it's possible.
b) When a) is not applicable, ask doc project to document it before commiting.
c) When neither a) or b) are possible, file a bug asking for doc
update for the commited changes.

-- 
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] [RFC] Features and documentation

[Doug Klima]

Alec Warner wrote:
> On 11/28/07, Donnie Berkholz <dberkholz@gentoo.org> wrote:
>   
>> On 19:10 Tue 27 Nov     , Alec Warner wrote:
>>     
>>> No, because this is not a realistic requirement, it's an ideal case.
>>> People will just commit changes without documentation anyway.
>>>       
>> Here's my understanding of what you said: Because people will break
>> rules and violate standards, we shouldn't have any.
>>
>> Is that accurate?
>>
>>     
>
> Kind of.
>
> Most people follow most rules.  Most people break a subset of rules.
>
> You are essentially adding an unreasonable (in my view) rule that I
> expect nearly everyone to break or ignore, thereby adding little or no
> value to the project as whole.  Most people care about documentation
> in the abstract sense, almost no one cares *enough* to write any ;)
>
> Forcing people to write documentation won't get it written, people
> will continue to act like we just saw and either the rule will get
> ignored, or someone will change the rule, or people will leave because
> the rule is enforced aggressively and it has ruined the ability to
> contribute to the project.
>
> This is why I offered to write the GLEP for Diego and Cardoe, because
> I know they are not interested in writing it themselves.  Thats why we
> have a doc-team that for some sick reason enjoy writing and
> maintaining documentation.
>
> -Alec
>   
Load of crap. I wrote full documentation and provided patches to the
Developer Handbook, where metadata is documented. A GLEP is a terrible
place to document this since you have to read through 5 different GLEPs
and automatically cross out the parts that are no longer valid or have
been replaced by newer parts of the GLEP. Which is why once again, the
GLEP is stupid and one central location on one topic should be kept up
to date. As I have done.
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: [RFC] Features and documentation

[Duncan]

Donnie Berkholz <dberkholz@gentoo.org> posted
20071129053854.GD11249@supernova, excerpted below, on  Wed, 28 Nov 2007
21:38:54 -0800:

> In fact, I believe exactly the opposite. What we want to create are
> basic philosophies to guide us. Nailing down a million tiny details is
> what makes things not fun, and what makes them impossible to learn.
> We're not trying to write a specification here, we're trying to come up
> with a set of guidelines that people could actually learn and remember.

OK, so you are deliberately going for the "big brush strokes" general 
guideline approach, and don't /want/ the policy getting into details.  I 
can respect that and will need to go back and reread the discussion to 
date with that in mind.

Meanwhile, you still sidestepped the other question.  Maybe it's getting 
too detailed also, but if so, directly saying so to that point would be 
nice, and if you just missed it, maybe this'll bring it to point:

Something must have motivated you to present this now.  What was it, or 
to put it a different way, how would have things been different in your 
view had this policy been in effect?  Point to other examples as well if 
you believe they'll help clarify the effect you intend this policy to 
have.

(BTW, I'm mailing you directly related to this as well.)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: [RFC] Features and documentation

[Santiago M. Mola]

On Nov 29, 2007 7:06 PM, Duncan <1i5t5.duncan@cox.net> wrote:
>
> Something must have motivated you to present this now.  What was it, or
> to put it a different way, how would have things been different in your
> view had this policy been in effect?  Point to other examples as well if
> you believe they'll help clarify the effect you intend this policy to
> have.
>

I don't know what kind of changes meant Donnie (I hope he clarify
that) but a couple of examples came to my mind when I read his
proposal: bugs #182253 and #181897. I'm sure there are much better
examples, but those are the ones I have right now.

Regards,
Santiago

-- 
Santiago M. Mola
Jabber ID: cooldwind@gmail.com
-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: [RFC] Features and documentation

[Steve Long]

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

[gentoo-dev] Re: [RFC] Features and documentation

[Duncan]

Steve Long <slong@rathaus.eclipse.co.uk> posted fiop46$9o$1@ger.gmane.org,
excerpted below, on  Fri, 30 Nov 2007 10:42:03 +0000:

> Duncan wrote:

>> It's kinda hard to discuss such a proposal without knowing where it is
>> going to be applied

> 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. [...] Additions would count too; I'd imagine
> someone adding a new feature would want others to know about it.

> I saw [this] 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 [...] 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.

OK.  That makes sense, and the last part agrees with the reply I got from 
the private inquiry I mentioned.  Quoting a single though from Donnie's 
reply:

> This isn't about punishing people. But it could be about
> reverting their commit until it comes back with documentation.

IMO people are (unfortunately correctly, given history) afraid of 
something being used to clobber them over the head.  If the above thought 
were included virtually verbatim in whatever is ultimately hard-proposed, 
I believe it'd go a LONG way to avoiding that, since the "clobber limits" 
are now clearly defined and (IMO) reasonable.

I guess I've been concerned that neither the reach of nor the weight of 
the "clobber stick" seemed limited in any way, and I think we've seen 
that an unlimited "clobber stick" isn't a good thing.  I was trying to 
limit the reach; Donnie didn't want that, but now I see his point that 
limiting the weight is equally abuse preventative, while less crippling 
to the effectiveness of the tool.

So provided a substantively similar "clobber limit" appears in the final 
proposal, I'm now supportive.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: [RFC] Features and documentation

[Duncan]

"Santiago M. Mola" <coldwind@gentoo.org> posted
3c32af40711291129m24b886edu24092291efac2281@mail.gmail.com, excerpted
below, on  Thu, 29 Nov 2007 20:29:31 +0100:

> I don't know what kind of changes meant Donnie (I hope he clarify that)
> but a couple of examples came to my mind when I read his proposal: bugs
> #182253 and #181897.

Good examples.  Thanks. =8^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

-- 
gentoo-dev@gentoo.org mailing list