cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glen Ezkovich <g...@hard-bop.com>
Subject Re: Planet Cocoon license and reuse of docs
Date Thu, 26 May 2005 17:05:35 GMT
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


Mime
View raw message