cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Per-Olof Norén <pe...@alma.nu>
Subject Re: Document Gestation Process?
Date Mon, 29 Apr 2002 16:40:32 GMT
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" <terracare@mac.com>
To: <cocoon-dev@xml.apache.org>
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 cocoon-docs@apache.org)? 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: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>




---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message