On Wed, Aug 8, 2012 at 2:29 AM, Bertrand Delacretaz <bdelacre...@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-unsubscr...@incubator.apache.org For additional commands, e-mail: general-h...@incubator.apache.org
