cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: [input needed] --- documentation questionnaire ---
Date Mon, 22 Apr 2002 07:40:43 GMT
Diana Shannon wrote:
> ---------
> 1. Assessing needs
<snip/>
> Note the meaning of following symbols:
>    +  existing documentation meets this need
>    -  existing documentation partially meets this need
>    o  no documentation currently meets this need
> 
> Evaluating C2 (new users, managers, administrators, press)
>    - conceptual, big-picture pieces
>    - news
>    - features
>    o requirements
>    o (links to) third party reviews, press
>    o success stories
>    o comparison to other technologies/approaches
>    o development roadmap

o Business cases
Various one-page exec summaries, that people can utilise
to convince their powers-that-be.
 
> Learning to use C2 (introductory/intermediate/advanced users)
>    - conceptual, big-picture pieces
>    - FAQs
>    - tutorials (multiple levels)
>    - guides to additional components
>    o manual
>    o learner's roadmaps
>    o glossary of terms
>    o (links to) external resources/aids
> 
> Developing with C2 (introductory/intermediate/advanced users)
>    + API reference
>    + Bug Database
>    - FAQs
>    - how-tos (download, build, install, configure, test, debug, extend, 
> etc.)
>    - sitemap components reference guide
>    - configuration reference guide
>    - samples/snippets/cookbook
>    - hosting information
>    o best practices
>    o (links to) external resources/aids
> 
> Contributing to C2 (community donations of code, documentation, 
> resources, etc.)
>    + Bug Database
>    + Code Respository
>    + to do (code)
>    + instructions (for developers)

- instructions (for developers)
... this area needs more work. As a new committer, i found
a lot of troubles getting started. It seemed that i was trying
to figure it out from scratch, e.g. to whom does one send
email about troubles with ssh/cvs (i.e. this is not public info).
I did gain clues by browsing doco from other projects.

>    o how-tos
>    o FAQs
>    o instructions (for all other types of contributions)
>    o source code style conventions
> 
> ---------
> 2. Accessibility
> Considering the documenation that already exists, how can we make it 
> more readily accessible? In other words, how can we reduce the amount of 
> time and effort required to locate and apply the necessary information? 
> How do we avoid information fragmentation? Please add/delete/edit as you 
> see fit.
> 
<snip reason="agree with all" />

Problem: Hard to know which documents have been updated
between releases.
Solution: Perhaps the generated Table-Of-Contents doclist
could be enhanced to show the last-modified date.

Problem: There is generally only one path to get to a certain
document 
Solution: Need more cross-references and better use of section
identifiers so that one document can refer directly to the relevant
section of another doc. Sometimes "content overlap" is necessary,
while sometimes it is better to refer to a section of some overview.

> -----------
> 3. What do you consider to be reasonable short- and long-term goals of 
> this effort? What should be the priorities?

Short-term:
*) Develop a set of planning documents (see below).
*) Improve doco which shows "how to contribute".
*) Develop a solid structure for FAQs (existing FAQ needs
to be split into various topic-based ones).
*) Develop a solid structure for HOWTOs. Should this
follow LinuxDoc or should it be based on our document.dtd ?
*) Concentrate on a couple of shining example HOWTOs
to get the ball rolling, which can serve as guidelines. It would
be a mistake to start off a mass of HOWTO documents with
minimal content and inconsistent layout.

Long-term:
*) Lead by example and encouragement.
*) Develop facilities to validate XML during build docs.
Trap any errors at the contributer's end. This eases the task
for a committer to apply a patch. At one stage, we did have
validation working, but it had to be switched off for some
obscure reason.

> -----------
> 4. How can we make the best use of available resources? How can we 
> leverage untapped resources within the Cocoon community?

Encourage the user community to "own" the documentation
along with the dev community. This is another of the big
opensource misconceptions. The general user thinks that
there is a separate "team of developers" that produce the
software/doco. 

> -----------
> 5. How do we focus our efforts to complement -- not compete with -- 
> third-party book and training efforts? ...<snip/>

Produce such brilliant on-line doco that it removes the need for
anyone to replicate it. In that way they can build upon the base
and concentrate their efforts on higher things.

> -----------
> 6. What documentation projects/examples do you admire? Any URLs or 
> specific references will be greatly appreciated.

FAQ-O-Matic.
SUNs original "Java Tutorial" Trails.
LinuxDoc.

> -----------
> 7. What's currently difficult about contributing/authoring documentation 
> for C2 right now? How can we improve that process?

I wonder if the general user realises the vision of
opensource, and that the onus is on them to fix any lack
that they perceive.

Perhaps they do not realise how easy it is to participate.
I think that a lot of people are afraid because they do not
understand. The section "CVS Usage Precis" recently
added to contrib.xml should help to encourage them to
send diffs rather than complaints.

> -----------
> 8. How can we make it easier/more inviting for people to participate in 
> the document development process? What kinds of architectural mechanisms 
> can we implement to support document development/refinement, given the 
> current hosting environment of Cocoon's web site?

*) Maintain a set of planning documents.
Perhaps we could keep a set of evolving documents in CVS.
A while back we did set up an area for "Planning". It has only
been used a little, but the structure is there ... src/documentation/plan/
We have often had such planning discussions before,
but content tends to remain hidden in the email archives.

*) The actual Cocoon website doco needs to be updated
far more regularly. At the moment, it is only updated when
a software release happens, which is not often enough.
A quicker turnaround on document edits, would encourage
more participation. Perhaps a separate doc-changes.xml

*) Keep doco development work on cocoon-dev list (we
cannot let developers get out of of this loop)
*) Encourage better use of email subject lines, and one
topic per thread.
*) Send planning summaries to cocoon-dev list regularly.
*) Send progress summaries to both lists. Perhaps an
automated summary can be generated each week to
show the documentation progress.

--David Crossley

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


Mime
View raw message