incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marvin Humphrey <mar...@rectangular.com>
Subject Re: [RT] a minimal set of docs for incubator.apache.org
Date Wed, 08 Aug 2012 18:05:18 GMT
On Wed, Aug 8, 2012 at 2:29 AM, Bertrand Delacretaz
<bdelacretaz@apache.org> wrote:

> How about starting a new, minimal set of docs that are more
> maintainable and understandable?

+1 to accepting that the end result of the documentation overhaul may be quite
different from what exists now.

-1 to starting from scratch rather than continuing the ongoing evolutionary
effort via progressive edits to the existing documents.

> IMO, the following would be sufficient, with one page per topic:
>
> 1. What's the Apache Incubator? (homepage)
> 2. Lifecycle of a podling, from proposal to graduation, with many
> links to existing examples (proposals, committer votes, graduation
> threads, etc.)
> 3. Release checklist: criteria for approving a release
> 4. Previously asked questions (a la
> http://www.apache.org/legal/resolved.html, includes IP clearance info)
> 6. Glossary of terms (though that might belong to the top-level
> apache.org site instead)

I don't believe that this proposed outline will meet your goals for
maintainability, because it is is not structured to take into account how the
Incubator docs evolve.  If we adopt this framework unmodified, I predict that
over time our docs will gradually decompose and revert to the current state of
incoherency.

The proposed "Previously asked questions" page, in particular, is doomed to
death-by-bloat.

The Incubator's documentation gets continuously updated by people who are
well-meaning but have a limited perspective.  If we don't provide outlets for
individuals to contribute what they are absolutely convinced is essential
material but is likely just their own pet best-practices tip, "minimal" docs
won't stay "minimal" for long.

In my opinion, we will achieve better results if we adopt a "hierarchical"
model: augment a minimal core with topical satellite pages (which lots of
people write to but fewer people read).  This paradigm is superior to
minimalism for two reasons:

First, the hierarchical model is sustainable while a purely minimalist
approach is toxic to community and incompatible with the Apache Way.
Rejecting contributions which do not fit within the tight scope of a
minimalist vision is costly -- it is dispiriting for the contributor and
exhausts the curator.  In contrast, when a curator merely *moves* a
contribution to a satellite page, less diplomatic effort is required and all
parties are more likely to be more-or-less satisfied with the end result.

Second, under a hierarchical model we are better able to make use of topical
contributions because they will be accessible by subject rather than thrown
into a catch-all like an FAQ page.  While the Java and Maven stuff was buried
in the giant pile of releasemanagement.html, no one had ownership of it.  Now
that release-java.html has been broken out, it has a decent shot at evolving
into something coherent and succinct that will serve Java podlings well.

> I've got some draft content for 2. and 3., that I've been collecting
> in my mentoring activities.

>From past experience, I know that the quality of your writing is high...  we
are not exactly lacking draft content, though, you know? :\  It would be great
to add your material to the collection of raw material that exists now, but I
don't see that it should displace everybody else's hard work.

Can you instead be persuaded to work with us on rewriting and editing down the
existing docs?  A lot of your draft material is likely to find its way into
the final product that way. :)

Marvin Humphrey

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org


Mime
View raw message