On May 25, 2005, at 4:40 AM, Linden H van der (MI) wrote:
Let me propose an entirely different strategy:
- pick a tool, any tool that meets the criteria I mentioned above and
start a new set of documentation there. I suggest Daisy.
What you should be concerned about is managing new and existing
content. This includes some process for accepting vetting, editing/
correcting and publishing.
- everyone who wants to write documentation should use THAT tool, that
repository to write his or her document.
Why require a particular tool? Is everyone who contributes code to
Cocoon required to use Eclipse?
Let's call this person a
writer. Before doing the actual writing we ask the writer to verify if
there is nothing on his topic in either wiki or 'official
documentation'. If there is, the writer should use the information
there
and add it to the document.
What if the new document is far superior to the existing in terms of
content and clarity? Who decides this? Do we leave this decision to
the author? Frankly if I'm going to write some documentation, I'm
going to do it because I'm unhappy with what exists and I am likely
to start from scratch or just completely rewrite what exists.
- there are several committers that are also concerned about the
documentation and make themselves heard in every thread about the
topic.
You guys know the code best and each probably has his own field of
expertise.
What I would suggest is that you volunteer to be editor/reviewer in
your
field of expertise. Your task in the documentation project will be to
review. So, the document written by a 'writer' is reviewed to see
if the
document is valid (i.e. the information is correct and current). If
you
feel something is missing you can either add it yourself of mark it
for
the original writer to add (based on time constraints). When both
of you
agree on the document it goes 'public', i.e. visible/usable for the
rest
of the community.
This is an essential step in producing good documentation. It is also
a very time consuming one. Experts are very useful when it comes to
verifying the broad pictures and approaches but to often their
knowledge of the field makes it easy for them to understand the
intention of the author when a newbie will be completely lost.
When a document goes public and it includes information from the wiki
and/or the 'official documentation' the editor replaces those pages
with
a link to the new document.
Unfortunately this leads to pretty much the same state we have now, a
lose collection of documents some easy to locate and some buried
deep. Someone needs to manage the documentation. Someone needs to
organize it. While this can be a community effort ultimately
decisions need to made as to where documentation is to be located and
organized and this needs to be done in a consistent manner.
I know in an open source community there are not much 'rules' to be
enforced, but if you can set up rules for committing code, you
might as
well set up rules for committing documentation.
The issues are different, but of course rules are needed. With code,
test can be run to verify correctness. Bugs pop up as others work on
different parts of the code. With documentation decisions need to
made by people as to its value, its understandability and where it
fits in the grand scheme of things. Someone needs to go through it
and insert the appropriate hyperlinks. Random documents no matter how
informative will not make Cocoon any easier. Its as much about
organization and ease of use from a users point of view as it is
about content and currency.
just my 1 1/2 cents
Glen Ezkovich
HardBop Consulting
glen at hard-bop.com
A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to
worry about answers."
- Thomas Pynchon Gravity's Rainbow
