Hi First off i´d like to emphasize the importance of good docs, and I think documentation will be as much of a moving target as the code (except the interfaces, of course :) ) Its good to have a process, granted, but php and postgresql have their "interactive docs", eg http://www.postgresql.org/idocs that allows users to add comments and enhancements to the docs. This of course only works when there is a "bone" to start out with, but since diana has been working on the structure, i guess it would be easy to generate the bone-docs as well as the needed authoring-guide. Now, I know we´d like to have our docs in xml, following dtd´s, which i suppose theese "idoc" tools doesn´t allow.
proposal/question: Can we use the "slash/edit" thing in scratchpad to construct an interactive documentation machine for cocoon? /Per-Olof Norén ----- Original Message ----- From: "Diana Shannon" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Monday, April 29, 2002 6:21 PM Subject: Re: Document Gestation Process? > > On April 29, 2002, Nicola Ken Barozzi wrote: > > >> 2. Author reads "How-To Write <document-type />". > > > > Contributing -> documentation > > Yes, there will be a link from the contributing section, but I thought > I'd demonstrate how to write a "how-to" by actually writing a few > how-tos. > > > > >> 3. Author consults topic status list (a web page on cocoon web site) to > >> make sure no other draft on this topic is in process. > > > > Or search on the aggregated titles page. > > Yes, but I want to minimize duplication of effort. But aggregated titles > alone may not show that a draft effort in process -- or would you add > its status? > > >> - If this review is handled off-list, could we set up a generic email > >> alias (like [EMAIL PROTECTED])? Emails could be forwarded to one > >> or > >> several committers, including myself, as well as stored? Don't we want > >> to ensure this process is not overly dependent on the responsiveness of > >> a single committer? > > > > I'd keep the process loose. > > Just propose, get /quick/ feedback, and write it. > > -1 for the mailing list. We did it for XSPs, and it was a complete > > failure. > > But don't you think documentation has a much broader scope/concern than > XSP? I take encouragement in the fact these efforts exist formally (and > appear to be working successfully) in other open source projects: Linux, > Zope, Apache, etc. > > > Besides, we don't get that many offers for documentation ;-) > > I think that fact reflects the maturity of an open source project. > Besides, Cocoon attracts content management people like myself. My > instincts tell me our existing users have a lot of skills and experience > they could bring to the effort. > > > > >> 5. If topic approved, author drafts outline and sends to editor for > >> review. > > > > To you? Ok :-) > > Yes, of course, but the point is to build a process that is sustainable > without the efforts of a single person. Granted, sustainability and > momentum won't happen overnight, but it should be the goal. > > >> <snip what="proposed steps 10-16" /> > > > > IMHO too much red tape. > > Maybe for an advanced writer, but what if an author actually wants this > feedback? Remember, I'm talking about users, not developers. > > >> Thanks for *any* input. > > > > Maybe more concise still? ;-) > > I'll keep trying, with your help ;) > > Diana > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, email: [EMAIL PROTECTED] > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
