FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Gentoo > Gentoo Development

 
 
LinkBack Thread Tools
 
Old 11-28-2007, 06:02 PM
Christian Faulhammer
 
Default Features and documentation

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/>
 
Old 11-28-2007, 08:14 PM
Donnie Berkholz
 
Default Features and documentation

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
 
Old 11-28-2007, 08:15 PM
Donnie Berkholz
 
Default Features and documentation

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
 
Old 11-28-2007, 08:33 PM
Ciaran McCreesh
 
Default Features and documentation

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
 
Old 11-28-2007, 11:29 PM
Donnie Berkholz
 
Default Features and documentation

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
 
Old 11-28-2007, 11:43 PM
"Alec Warner"
 
Default Features and documentation

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
 
Old 11-29-2007, 12:01 AM
Donnie Berkholz
 
Default Features and documentation

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
 
Old 11-29-2007, 01:25 AM
"Alec Warner"
 
Default Features and documentation

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
 
Old 11-29-2007, 04:04 AM
Duncan
 
Default Features and documentation

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
 
Old 11-29-2007, 04:38 AM
Donnie Berkholz
 
Default Features and documentation

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
 

Thread Tools




All times are GMT. The time now is 12:56 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org