You are viewing a plain text version of this content. The canonical link for it is here.
Posted to community@apache.org by "Noel J. Bergman" <no...@devtech.com> on 2003/06/19 05:09:39 UTC
Common documents across the ASF
[Moving from infrastructure@ and Jakarta PMC@]
Danny,
I agree with what you said. And I didn't suggest "taking" content away from
any Community. That was someone else's reaction to my observation. My
interest is to have shared content. If Jakarta is THE place for us all to
put appropriate content, fine.
Centralizing content related to best practices for Java projects in the
Jakarta structure makes sense. That might include technical content such as
using the site modules, doing builds, using java related tools, perhaps
using JNLP, whatever. That would be unique information that Jakarta
maintains, differentiated from content related to project policies and
procedures in general.
For example, policies related to project structure, voting, getting
Committers setup, etc., are common across the ASF. Having three different
sets of instructions for how to request a new Committer, multiple versions
of the CLA, different pages of CVS instructions, etc. isn't productive. A
project specific page with project specific examples and content is fine,
but IMO the general stuff should be referred to a common page where it can
be maintained when those procedures are modified. Again, I don't especially
care where that common page resides.
As an observation, since the sites are published directly from CVS modules,
CVS organization is causing documentation to be partitioned by project.
Perhaps some site modules need to be more open so that the content can be in
the organized appropriately for the web. Perhaps it is the content under
www.apache.org/dev that should be moved to some place else central for
everyone. I care about about sharing and reuse, not location.
I see this as increasing unless there is a consensus to share documents.
Consider Incubator. Incubator also has a set of instructions for how to
process a new Committer. One of the statements made is that projects should
"direct the new committer to the Apache Incubator site for a better
explanation of life here at Apache." On that page is a comment from Nicola
Ken saying that in addition to the links back to the common files under
www.apache.org/dev, Incubator also "[needs] a page like Jakarta newbie."
I don't really care if these documents are under Incubator, apache.org, or
Middle Earth, but how many copies of the same material do we want to
maintain, and where? We consider reuse a best practice in code. I consider
it a best practice for documentation, and am simply trying to express that
opinion.
Why NOT have shared documents? I've heard it said that the CVS organization
is the barrier. OK, so why not look at what reasonable steps could relieve
that barrier? What would happen if we had an Incubator module open to all
ASF Committers? Would that lower the barrier and increase reuse?
--- Noel
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by Leo Simons <le...@apache.org>.
Noel J. Bergman wrote:
>Why NOT have shared documents?
>
go for it dude :D. You will have to battle NIH syndrome and general
resistance to any kind of change.
cheers,
- Leo
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
RE: Common documents across the ASF
Posted by "Noel J. Bergman" <no...@devtech.com>.
> There's the "committers" module. Every committer has access to this one.
I know. It isn't part of the site deployment, but I suppose that it could
be used that way, perhaps under the docs/ directory (for example), with a
small change to the update commands. Also, the Committers module is, AIUI,
considered to have private content.
--- Noel
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by Leo Simons <le...@apache.org>.
Tim,
you missed my point. Sander asked whether commit access is, or is seen
as, a barrier.
The answer is: yes. It is one of many barriers that we have. You're
pointing out that
those are in place for a reason. Well, yeah.
For example, commit priviledge is something which is earned by
individuals and given out
by a community, hence facilitating a "community" feel. Someone who is
granted committer
status usually feels honoured to be asked to be part of the team. Works
nicely.
Now the catch: for some stuff, I happen to think some current barriers
don't make sense.
They result in lots of unneccessary duplication (of effort and material).
"general" documentation is one of those areas. A low barrier to
cross-project co-operation
on stuff like that will help avoid pages like
http://httpd.apache.org/dev/nt-cvs-ssh.txt
IOW, this is not about technical difficulty or community dynamics, it is
about managing
the path of least resistance for a common cross-project concern which is
completely
orthogonal to the reason(s) for the existence of our barriers.
cheers!
- Leo
Tim O'Brien wrote:
<rant-disclaimer/><snip/><stuff/>
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
RE: Common documents across the ASF
Posted by "Noel J. Bergman" <no...@devtech.com>.
> I don't see the issue as people not wanting to write documentation,
> just individuals taking the path of least resistance.
I agree.
> Honestly, I'm curious as to how much authority the individual PMCs
> should be exercising to define these processes. Even a process as
> simple as creating an account for a first time creator can have
> variations.
I think that the answer depends upon within whose domain the item resides.
In the case of account creation, that action item resides in the
infrastructure group. They, and no one else, should have control over the
procedure(s) involved with respect to the action item. With respect to
internal project management, that's the PMC's call.
In the case of project management, each PMC ought to be able to define its
own policies and procedures within the broad guidelines provided by the ASF
(perhaps via Incubator and/or Jakarta as the holder of "best practices.").
If a PMC wants to do things differently, or "subclass" a procedure, that's
up to the PMC, IMO.
I don't see shared documents as being about control. I see it as being
about reuse and ease of access. On the latter issue, I've started a page at
Greg's suggestion (and looked on the Wiki first to see if there was one),
whose sole purpose is to act as a TOC. If an existing Wiki page had already
collated information on a particular topic, I just linked to that Wiki page
(re-use) rather than re-implement that effort.
--- Noel
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by Serge Knystautas <se...@lokitech.com>.
Tim O'Brien wrote:
>>no, the barrier is not high. Yes, it is too high for many, many potential
>>contributors.
>
> No it isn't, I think you are confusing the fact that people don't
> generally like to contribute documentation. Instead of lowering the
> barriers for "potential contributors", we need to do a better job of
> creating an atmosphere where a non-committer knows that a patch submission
> will not sit in Bugzilla for months before being "discovered".
I would tend to agree with your rant and your suggestion on how to earn
karma.
However, committers on individual projects are using their own CVS
modules to create copies of these documents. We on the James project
have done this with a few pages and link to some Jakarta or Apache
website pages depending on which we think is best written/most updated.
So, I don't see the issue as people not wanting to write
documentation, just individuals taking the path of least resistance.
Honestly, I'm curious as to how much authority the individual PMCs
should be exercising to define these processes. Even a process as
simple as creating an account for a first time creator can have
variations. This is a silly example, but the Jakarta page says to cc
this request to pmc@, while we at James are cc'ing general@. Also the
James project might want to specify that "lazy" consensus for a new
committer vote is waiting 72 hours from the time the vote is called.
Other projects may have this a different time, or even just think the
James project is making a mountain out of a mole hill and should get
over themselves.
Isn't to some extent these processes decisions up to the PMC? Do we
really have so many variations that the board (or members or whoever)
need to decide what to centralize and unify?
--
Serge Knystautas
President
Lokitech >> software . strategy . design >> http://www.lokitech.com
p. 301.656.5501
e. sergek@lokitech.com
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by Tetsuya Kitahata <te...@apache.org>.
On Thu, 19 Jun 2003 13:58:45 -0400 (EDT)
"Tim O'Brien" <to...@discursive.com> wrote:
> The docs I think people are talking about are more analogous to the
> Magna Carta, or a legal document.
As you mentioned the legal issue, can I speak up my point of view?
(superfluous to some extent)
---------------------------------------------------------------------
Please see,
http://jakarta.apache.org/bsf/index.html
http://jakarta.apache.org/ecs/index.html
http://jakarta.apache.org/jetspeed/site/index.html
http://jakarta.apache.org/jmeter/index.html
http://jakarta.apache.org/slide/index.html
http://jakarta.apache.org/taglibs/index.html
http://jakarta.apache.org/watchdog/index.html
and the bottom of these pages.
Why do their 'copyright' not include the year 2003?
These projects are mothballed, stopped their activities?
Or, the committers of each projects just forgot to append the "2003"??
Or, they do not know how to???
--
Next: about the new logo of jakarta:
('Logo' is one of the most important intellectual properties
for most of the companies, generally speaking)
Most of the jakarta-commons subprojects and mavenized projects
still seem to stick to use older jakarta-logo (except jelly), not
knowing the fact that new jakarta-logo had been created last year
(Oh, this goes for jakarta-slide site, too).
Partially most of the developers/committers do not pay much attention
to their sites, to say nothing of the outside of their sites. For new
comers, even 'jakarta' seems to divide against itself at a glance,
I suppose.
Can non-committers submit patches for these (binary), and do these
actions make sense?
--
Are these above allowable 'diversity'?
I do not intend to offend anyone. Just putting up my
ingenuous questions what came to my mind a long time ago....
Sincerely,
-- Tetsuya (tetsuya@apache.org)
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
RE: Common documents across the ASF
Posted by Tim O'Brien <to...@discursive.com>.
On Thu, 19 Jun 2003, Noel J. Bergman wrote:
> > I think you are confusing the fact that people don't generally
> > like to contribute documentation.
>
> Although I consider this orthogonal to shared pages (people can cut and
> paste vs. link on the Wiki as easily as the static sites), I do believe that
> lowering the barrier (CVS or XML) has demonstrably increased documentation
> contribution.
Agreed, there is a problem in that guidelines and policies are duplicated
across the apache.org domain and sometimes presented in draft form on the
site. This leads to confusing situations where two people disagree on
process, who can propose a release, what is a PMC, etc.
> In the case of James, we have had far more contribution to our pages via the
> Wiki from normal users, than their taking time to learn the XML
> documentation scheme. Users feel directly empowered. But I consider shared
> content and Wiki use to be unrelated.
I consider these issues to be unrelated as well. I'm not questioning the
value of the Wiki, I think it has worked for the projects that have
decided to use it, but from what I see it is no substitute for documents
that need to be viewed as "policy".
The docs I think people are talking about are more analogous to the Magna
Carta, or a legal document.
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
RE: Common documents across the ASF
Posted by "Noel J. Bergman" <no...@devtech.com>.
> I'm tired of having someone propose a new committer because he
> or she thinks that the patch submission process is "too difficult".
In my case, I'm talking about existing Committers. *If* CVS commit rights
for Committers are widely perceived to be a barrier, then perhaps there
ought to be a place where Committers can equally contribute to a shared
document set. But the whole world? Use the Wiki.
> I think you are confusing the fact that people don't generally
> like to contribute documentation.
Although I consider this orthogonal to shared pages (people can cut and
paste vs. link on the Wiki as easily as the static sites), I do believe that
lowering the barrier (CVS or XML) has demonstrably increased documentation
contribution.
A lot of documentation has been building on the Wiki. Perhaps more than on
the official sites over the period. Some projects are moving their FAQ
pages to the Wiki. I am not promoting or discouraging that approach, but am
curious to see how it evolves.
In the case of James, we have had far more contribution to our pages via the
Wiki from normal users, than their taking time to learn the XML
documentation scheme. Users feel directly empowered. But I consider shared
content and Wiki use to be unrelated.
--- Noel
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by Tim O'Brien <to...@discursive.com>.
On Thu, 19 Jun 2003, Leo Simons wrote:
<rant-disclaimer>
Why do people think submitting patches is difficult?
Maybe I just woke up on the wrong side of the bed this morning, but I'm
tired of having someone propose a new committer because he or she thinks
that the patch submission process is "too difficult". CVS, patch, and
email are not difficult subjects to master.
> - learn how to generate patch
> - figure out where to send the patch
> - generate patch
> - type e-mail
> - send patch with e-mail to infrastructure list
> - followup on the responses
> - make a change to your patch as requested by infrastructure
> team
> - send another e-mail
This process is part of the community process. If you continue to submit
patches with merit, you'll probably end up with karma. :-) If you are in
a rush to contribute code to a project, go to SourceForge or java.net and
start a documentation project.
</rant-disclaimer>
<snip/>
> no, the barrier is not high. Yes, it is too high for many, many potential
> contributors.
No it isn't, I think you are confusing the fact that people don't
generally like to contribute documentation. Instead of lowering the
barriers for "potential contributors", we need to do a better job of
creating an atmosphere where a non-committer knows that a patch submission
will not sit in Bugzilla for months before being "discovered".
Tim
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by Leo Simons <le...@apache.org>.
Sander Striker wrote:
>Hang on a minute. Why does everyone need commit access to this one? All ASF
>members have commit access to it. And more than a few others. I'm sure it
>isn't that hard to find someone to commit sent in patches. Is generating
>and sending in a patch considered too high a barrier?
>
for many people, yes!! It is very hard to even find people willing to
work on
documentation, and when you do find them if you make it even slightly
nontrivial to do their thing, they will often JustDoIt elsewhere or not
at all.
that's why wikis are so successful: their barrier to entry is extremely
low. Between
finding an error or area that deserves improvement and actually seeing
the change you
made live on the website are 30 seconds with a wiki instead of two days
or more for
a patch.
for example, there is a useful bit of info about cvs @
http://wiki.cocoondev.org/Wiki.jsp?page=CvsAndFirewalls
that would be nice to have on www.apache.org/dev/.
Consider the amount of overhead for the average casual apache contributor
in getting it up on that page. It involves something like:
- navigate the wiki for place to add the page
- click "edit this page"
- add a new link
- click "save"
- click the new link
- enter content
- click preview
- verify correctness, edit again
- click save
time taken? maybe a minute or so if you're familiar with wikis, maybe
15 minutes if you're not.
now consider how one gets this information up on www.apache.org/dev/:
- navigate the site for place to add the page
- figure out where/how the site is maintained
- read the documentation on how to help maintain it
- check out relevant cvs modules
- learn anakia xml format
- find the xml file to edit
- transform content to xml, add page
- add link to this new page from the faq
- run anakia
- view results
- verify correctness, edit again, run anakia again
- learn how to generate patch
- figure out where to send the patch
- generate patch
- type e-mail
- send patch with e-mail to infrastructure list
- followup on the responses
- make a change to your patch as requested by infrastructure
team
- send another e-mail
- check whether the patch was properly applied and the
website was properly generated
time taken? maybe 10 minutes if you've got experience with submitting
patches,
using ant and anakia, etc. Maybe an hour or two if you're not. Not
counting the
time taken by the person applying the patch.
The latter process is acceptable for software, but for documentation it
means
that oh, lets say, 95% of your potential documentation contributors do not
even bother to contribute.
Now, giving lots of people cvs commit access does not make all that easier,
but it replaces all of
- learn how to generate patch
- figure out where to send the patch
- generate patch
- type e-mail
- send patch with e-mail to infrastructure list
- followup on the responses
- make a change to your patch as requested by infrastructure
team
- send another e-mail
with
- commit the change
which might cut time taken in half for your average jakarta committer
who has
experience with using ant, anakia and cvs.
no, the barrier is not high. Yes, it is too high for many, many potential
contributors.
I can hear you think, "yeah, but a wiki doesn't have enough security". Well,
applying standard risk assessment practices, I would think that HTTP basic
authentication with passwords available to anyone with an @apache.org
e-mail account is enough protection for the content on www.apache.org/dev/.
We really don't need public key SSH encryption and CVS commit right
partitioning here.
back into my corner! cheers,
- Leo
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
RE: Common documents across the ASF
Posted by "Noel J. Bergman" <no...@devtech.com>.
Sander,
You said, "Hang on a minute. Why does everyone need commit access to this
one? All ASF members have commit access to it." I had asked, "What would
happen if we had an Incubator module open to all ASF Committers? Would that
lower the barrier and increase reuse?"
Are you referring to ASF Members, as opposed to Committers, having commit
access to the site module? If so, I don't disagree that perhaps the ASF
site module need not be opened, but is there a reason not to allow all
Committers to update common documents related to procedures and other
project matters? Perhaps not in the site module, but in another suitable
module?
> I'm sure it isn't that hard to find someone to commit sent in patches.
> Is generating and sending in a patch considered too high a barrier?
According to the posts in infrastructure@, at least some people would sooner
copy text from a page into their own CVS than submit patches.
--- Noel
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
RE: Common documents across the ASF
Posted by Sander Striker <st...@apache.org>.
> From: Jeremias Maerki [mailto:dev.jeremias@greenmail.ch]
> Sent: Thursday, June 19, 2003 8:52 AM
> There's the "committers" module. Every committer has access to this one.
>
> On 19.06.2003 05:09:39 Noel J. Bergman wrote:
> > Why NOT have shared documents? I've heard it said that the CVS organization
> > is the barrier. OK, so why not look at what reasonable steps could relieve
> > that barrier? What would happen if we had an Incubator module open to all
> > ASF Committers? Would that lower the barrier and increase reuse?
Hang on a minute. Why does everyone need commit access to this one? All ASF
members have commit access to it. And more than a few others. I'm sure it
isn't that hard to find someone to commit sent in patches. Is generating
and sending in a patch considered too high a barrier?
Sander
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by Jeremias Maerki <de...@greenmail.ch>.
There's the "committers" module. Every committer has access to this one.
On 19.06.2003 05:09:39 Noel J. Bergman wrote:
> Why NOT have shared documents? I've heard it said that the CVS organization
> is the barrier. OK, so why not look at what reasonable steps could relieve
> that barrier? What would happen if we had an Incubator module open to all
> ASF Committers? Would that lower the barrier and increase reuse?
Jeremias Maerki
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
RE: Common documents across the ASF
Posted by "Noel J. Bergman" <no...@devtech.com>.
Glen,
> The reason why it hasn't been done is simple... because no one
> has actually stepped up to find all the redundant information
> and send patches to the various projects to fix it up. CVS
> access isn't the problem. Finding someone with the itch, time
> and motivation is.
That is the answer I would have hoped (and expected) to hear. It wasn't
what I heard.
A bit of background. I had made a comment about shared documents on
infrastructure@ in response to someone saying that for most Java
programmers, Apache is Jakarta, and they never ever look at
www.apache.org/dev. In response to my comment about the desirability of
centralizing sharing policy and procedure documents to make them easier to
reference and maintain, I heard:
- "you could move the dead content to the ASF but you would not be
moving the community that created and maintains it."
- "if these pages were removed into the central site then this
would be a much bigger barrier and take a lot more energy.
unless i felt very strongly, i'd probably not bother. i'd
probably add the information to a jakarta subproject website."
- "it's not reasonable to expect the jakarta pmc to enforce what
you describe. i would not support any veto of a change to the
website on the basis that the material should have been
submitted to the ASF site."
Emotional, real or otherwise, there is at least a non-unique perception that
having to submit a patch is far more work that vs committing directly. That
was one of the reasons given for why people copy documents into their own
CVS space, rather than build shared content for the ASF community.
Right now the sample size is tiny, so I would not make any claims as to the
overall attitude towards shared content. I hope that your view is the more
common one.
Meanwhile, I have created
http://nagoya.apache.org/wiki/apachewiki.cgi?PoliciesAndProcedures, which
just attempts to collect and collate policies and procedures pages that
people (in the initial dump, me) think have shareable content. It is a
first step to let us all "[step] up to find all the redundant information."
--- Noel
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by robert burrell donkin <rd...@apache.org>.
On Thursday, June 19, 2003, at 05:31 AM, Glen Stampoultzis wrote:
> At 01:09 PM 19/06/2003, you wrote:
>
> Why NOT have shared documents? I've heard it said that the CVS
> organization
> is the barrier. OK, so why not look at what reasonable steps could
> relieve
> that barrier? What would happen if we had an Incubator module open to all
> ASF Committers? Would that lower the barrier and increase reuse?
>
>
>
>
> The reason why it hasn't been done is simple... because no one has
> actually stepped up to find all the redundant information and send
> patches to the various projects to fix it up. CVS access isn't the
> problem. Finding someone with the itch, time and motivation is.
it's not as simple as that. the proposal is not only to create common
documentation (which would be cool) but also to remove all existing
documentation on subjects which should be common. this means removing most
of the pages on the jakarta website.
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org
Re: Common documents across the ASF
Posted by Glen Stampoultzis <gs...@iinet.net.au>.
At 01:09 PM 19/06/2003, you wrote:
>Why NOT have shared documents? I've heard it said that the CVS organization
>is the barrier. OK, so why not look at what reasonable steps could relieve
>that barrier? What would happen if we had an Incubator module open to all
>ASF Committers? Would that lower the barrier and increase reuse?
The reason why it hasn't been done is simple... because no one has actually
stepped up to find all the redundant information and send patches to the
various projects to fix it up. CVS access isn't the problem. Finding
someone with the itch, time and motivation is.
Glen Stampoultzis
gstamp@iinet.net.au
http://members.iinet.net.au/~gstamp/glen/