[RT] a minimal set of docs for incubator.apache.org

[Bertrand Delacretaz <bd...@apache.org>]

Hi,

Like others, I'm not too happy with the current
http://incubator.apache.org/ content.

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

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'm just considering the narrative info, not the podling status pages
or clutch stuff in this refactoring. That status info might move to
podlings.incubator.apache.org to better separate it and keep the main
site minimal.

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

WDYT?

-Bertrand

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

Re: [RT] a minimal set of docs for incubator.apache.org

[Gary Martin <ga...@wandisco.com>]

Committing somewhere would be good as otherwise I don't know whether I 
need to suggest the following (I wasn't sure of the best thread for this 
to go in anyway):

    May I suggest that, where appropriate, the documentation is backed
    up with pointers to examples of existing projects that are
    considered to represent the current best practice on various
    aspects. Whilst clear documentation is fantastic, there is nothing
    like good examples for building confidence that one is doing things
    in the right way.

Cheers,
     Gary


On 08/08/2012 10:42 AM, Greg Stein wrote:
> Commit the content. Otherwise, we're just hand-waving.
> On Aug 8, 2012 5:29 AM, "Bertrand Delacretaz" <bd...@apache.org>
> wrote:
>
>> Hi,
>>
>> Like others, I'm not too happy with the current
>> http://incubator.apache.org/ content.
>>
>> How about starting a new, minimal set of docs that are more
>> maintainable and understandable?
>>
>> 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'm just considering the narrative info, not the podling status pages
>> or clutch stuff in this refactoring. That status info might move to
>> podlings.incubator.apache.org to better separate it and keep the main
>> site minimal.
>>
>> I've got some draft content for 2. and 3., that I've been collecting
>> in my mentoring activities.
>>
>> WDYT?
>>
>> -Bertrand
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
>> For additional commands, e-mail: general-help@incubator.apache.org
>>
>>

Re: [RT] a minimal set of docs for incubator.apache.org

[Greg Stein <gs...@gmail.com>]

Commit the content. Otherwise, we're just hand-waving.
On Aug 8, 2012 5:29 AM, "Bertrand Delacretaz" <bd...@apache.org>
wrote:

> Hi,
>
> Like others, I'm not too happy with the current
> http://incubator.apache.org/ content.
>
> How about starting a new, minimal set of docs that are more
> maintainable and understandable?
>
> 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'm just considering the narrative info, not the podling status pages
> or clutch stuff in this refactoring. That status info might move to
> podlings.incubator.apache.org to better separate it and keep the main
> site minimal.
>
> I've got some draft content for 2. and 3., that I've been collecting
> in my mentoring activities.
>
> WDYT?
>
> -Bertrand
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>
>

Re: [RT] a minimal set of docs for incubator.apache.org

[Marvin Humphrey <ma...@rectangular.com>]

On Wed, Aug 8, 2012 at 2:29 AM, Bertrand Delacretaz
<bd...@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