Helma,
I don't want to discourage the effort to create a or deploy a Cocoon
based CMS. I think its important that it gets done. My point is that
no mater how easy and automated the process becomes, good
documentation requires a great deal of human collaborative effort.
On May 25, 2005, at 8:30 AM, Linden H van der (MI) wrote:
- 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.
In short a CMS type of tool
LOL I'm a big believer in automation but I think its to much to ask
of a CMS to vet, edit and correct documents. ;-) Let me be clear, a
CMS is an important tool that needs to be in place to help manage the
process. When a document is submitted someone must read it. Upon
reading it, they make a judgement as to whether it meets some
criteria of acceptability. If deemed acceptable it is then vetted by
"experts". The experts make suggestions concerning content. The
author and her expert collaborators make changes to the content. At
this point an "editor" will examine the document for readability,
spelling and grammar. The editor in collaboration with the author
corrects and improves the document. Once all corrections are made,
the author, experts and editor sign off on it and the document is
formated and published.
Until the document is formated what we are dealing with is pure
content. We shouldn't care about layout, formatting, hyperlinks or
anything other then the documents content. It is at this point one
may choose the editor provided by the CMS to convert the source
document, but it is not the only choice. It can be done by hand or
better yet, automated. Once the original document is published the
role of the CMS is to manage and facilitate updates to the document.
It is at this point that an online editor becomes useful for small
changes. Substantial changes are best handled by the same process
that created the original document. The role of the CMS is to
facilitate this workflow.
My argument is not with the need for a CMS but with the vision of how
it will be used to improve the documentation but providing a simple
single creation and editing entry point.
Why require a particular tool? Is everyone who contributes code to
Cocoon required to use Eclipse?
Since documentation is best gathered in a CMS, because there will
likely
(hopefully) be more than one person working on it, this inevitably
means
that everyone should use THAT CMS to avoid scattering documentation
all
over the place (wiki, website, mailing list, blogs, own websites etc).
I don't think a CMS will alleviate this problem. Wikies, websites,
mailing lists, blogs etc. are the most suitable places for some forms
of documentation. A CMS will allow the fromal Cocoon community to
better manage the content which it owns.
What if the new document is far superior to the existing in terms of
Hurray for that. But if you've come up with something that replaces
information in other places, do note that in both "origin" and
"destination" to avoid others duplicating the effort.
Yes, the human element creeps in again. Someone needs to decide that
one document is superior to another and replace the old with the new.
When such a change occurs the community should be notified as well.
Depreciated documentation is documentation none the less. I believe
the new improved documentation should provide a reference and a link
to the documentation it replaces.
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.
Great! Go ahead. If you feel comfortable enough to write something
about
any aspect of Cocoon, please do. The only thing I ask from reviewers
(aka Cocoon committers) is that they read your document and compare
what
you write to the actual working of Cocoon to see if there are
discrepancies that might lead to false conclusions/understanding from
other users.
I certainly hope that they would. If they find errors I want to know
about them and correct them. I really should get off may lazy ass and
do it.
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.
OTOH If you write down that CForms has a state 'readonly' when in fact
it's 'disabled' that's something Sylvain e.g. will probably notice
immediately while it takes trial and error of 'ordinary' users to
figure
out.
Certainly. Thats why we need domain experts and documentation
writers. Rarely is one individual superior in both areas.
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.
True, but even the multiple attempts to come up with a general TOC
have
failed so what now? Putting all documentation in one place (at
least the
'user guide' type which is most needed anyway), following a general
structure/TOC is still better than the current state.
Yes. Its not so much a general TOC but one that is actively
maintained to reflect the current state of the content. Cocoon is a
dynamic project and as such its documentation needs to be dynamic as
well.
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.
Ok. Let's sit down then and dream up a general TOC by studying the
attempts done earlier.
I guess we could learn from their mistakes. ;-) Assuming that the
documentation will grow and change over time, so will the TOC. On the
other hand, if you view the TOC as a model of Cocoon's documentation
we can at least have a starting point for our first documentation
sprint. I think this is worthy of some more discussion. I have some
free time this weekend (I hope) and will sit down and look at the
documentation. I think its worth while to expend some effort in
charting a course for Cocoon's documentation. The one thing I know I
would like to see is the syncing of documentation with development.
This would be a gargantuan effort because there are many small
changes that occur with each release, but I believe the benefit to
users and developers would be worth the effort.
Lets examine the current documentation, develop a vision for its
future and actually work towards achieving that vision. I am willing
to commit to participating in the effort to both develop the plan and
to implement it.
I've always thought we needed an XD to complement XP. Lets find out
if it will work.
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
