You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by "Linden H van der (MI)" <H....@MI.unimaas.nl> on 2005/06/13 09:33:26 UTC
[VOTE] Consensus about documentation location
Guys,
I'm aware that I'm not officially a committer (yet), however, I think it
will be a good idea to get explicit consensus on where to locate the
docs and about a rough outline of the future actions.
This is the proposal:
- the current Daisy site at the zones [1] will be the "incubator" for
the new documentation. I.e. new content is to be entered there.
- this documentation is targeted at Cocoon 2.2. This means that we try
to write version-independent documentation, but when there is a
difference between 2.1 and 2.2, the documentation will describe 2.2.
- the rules for the various roles have been defined already [2]. Note,
registered guests can leave comments.
- this also implies that we stick with Daisy as CMS (and not venture on
the endless hunt for THE best system/toolset).
- all current content in both wiki and "official docs" will be evaluated
and either deprecated or moved over into the Daisy site.
- once the wiki is "processed" (i.e. all documentation is (re)moved), it
will only serve as a scratchpad, either for random thoughts/proposals or
for users that want to offer documentation but have no editor rights in
the Daisy site. I.e. the content of the wiki should be kept as small as
possible and deprecated information should be removed as soon as
possible.
- the current intention is to eventually move the content of the Daisy
site over to the "official documentation". This is no hard coded rule
and may be changed later.
[1] http://cocoon.zones.apache.org/daisy/cocooninaction/4.html
[2] http://www.mail-archive.com/dev@cocoon.apache.org/msg31807.html
Bye, Helma
Re: [VOTE] Consensus about documentation location
Posted by Leszek Gawron <lg...@mobilebox.pl>.
Ralph Goers wrote:
> Sylvain Wallez wrote:
>
>>
>> Same concerns as Ugo. We should IMO document 2.1 and use specially
>> labelled sections and pages for what's different in 2.2. We could also
>> uses Daisy branches, but I don't think it's a good idea to start a
>> multi-branch effort right now.
>
>
> I agree with this also.
>
>>
>>
>>> - once the wiki is "processed" (i.e. all documentation is (re)moved), it
>>> will only serve as a scratchpad, either for random thoughts/proposals or
>>> for users that want to offer documentation but have no editor rights in
>>> the Daisy site. I.e. the content of the wiki should be kept as small as
>>> possible and deprecated information should be removed as soon as
>>> possible.
>>>
>>>
>>
>> Same concerns as Leszek: writing docs in the wiki would really make
>> non-editors feel like second-class citizen. Additionally to leaving
>> comments, we may allow registered users with no particular rights to
>> edit documents belonging to a "scratchpad" collection, distinct from
>> the main document collection. That will allow us to quickly move
>> around good contributions to the main area and also educate editor
>> wannabees to the CMS features.
>
>
> Here I have to disagree with you. I don't think that all the content
> that is on the Wiki should necessarily find its way to the :"formal"
> documentation. I think the wiki serves that purpose well. It allows
I do not propose to give access do editing formal documentation. Daisy
has got a nice feature of several "sites" in one CMS. Let's make a
scratchpad site that allows users to enter their experiences there.
> users a place to document things that they have learned which may not
> have a good place in the formal documentation.
What kind of documentation, faq, recipe, howto is not suitable for
formal documentation? Every piece of someones writing can be:
- pointed out to have an existing docs entry
- processed and incorporated into formal docs somehow (I do not mean 1:1
here)
- rejected because of quality issues
> So, just because users
> can't directly update the formal documentation I don't think they will
> feel like second class citizens. I think they'd be quite surprised if
> they could update the formal documentation. And actually, I think they
> would be quite pleased and honored if whatever they wrote was moved from
> the wiki into the formal docmentation by an editor.
>
> I really don't see this as much different than how things are with the
> code. Users can write patches and submit them to bugzilla or they can
> post code snippets on the wiki, but they cannot update svn.
I see an analogy but I keep my opinion:
- it will be much more appealing to users to post snippets to CMS scratchpad
- reviewing things and putting them live will happen using the same
tools as for formal documentation (who will want to convert wiki markup
-> html code?)
- Most of all: we will have one documenatation source instead of 2. Even
if something is in scratchpad people may want to look for it and use it.
We could provide special search queries for formal documents only and
one that would include awaiting documents.
--
Leszek Gawron lgawron@mobilebox.pl
IT Manager MobileBox sp. z o.o.
+48 (61) 855 06 67 http://www.mobilebox.pl
mobile: +48 (501) 720 812 fax: +48 (61) 853 29 65
Re: [VOTE] Consensus about documentation location
Posted by Glen Ezkovich <gl...@hard-bop.com>.
On Jun 13, 2005, at 8:46 AM, Ralph Goers wrote:
> Sylvain Wallez wrote:
>
>
>>
>> Same concerns as Ugo. We should IMO document 2.1 and use specially
>> labelled sections and pages for what's different in 2.2. We could
>> also uses Daisy branches, but I don't think it's a good idea to
>> start a multi-branch effort right now.
>>
>
> I agree with this also.
>
I know how slowly I can work sometimes, so 2.2 is a good target for
me. ;-) I think what we want is to have current documentation. When
2.2 is released we want to be ready. We don't want to go back and
update documentation that we have just finished, especially if we
could have incorporated it as we went along. Likewise I don't see us
ignoring 2.1, since no one in there right mind would ever use the
latest relaease :-O. We can't document anything that doesn't exist
yet, but we do have to work with the latest versions in order to stay
current. If developers are working on 2.2, the documentarians need to
be as well. Right now I think each of the "documentarians" has a pet
project. What I hope is that in the future (or even now) that if
commiters need new functionality documented they will feel free to
ask us to do it. That is the role we play.
>
>>
>>
>>
>>> - once the wiki is "processed" (i.e. all documentation is (re)
>>> moved), it
>>> will only serve as a scratchpad, either for random thoughts/
>>> proposals or
>>> for users that want to offer documentation but have no editor
>>> rights in
>>> the Daisy site. I.e. the content of the wiki should be kept as
>>> small as
>>> possible and deprecated information should be removed as soon as
>>> possible.
>>>
>>>
>>
>> Same concerns as Leszek: writing docs in the wiki would really
>> make non-editors feel like second-class citizen. Additionally to
>> leaving comments, we may allow registered users with no particular
>> rights to edit documents belonging to a "scratchpad" collection,
>> distinct from the main document collection. That will allow us to
>> quickly move around good contributions to the main area and also
>> educate editor wannabees to the CMS features.
>>
>
> Here I have to disagree with you. I don't think that all the
> content that is on the Wiki should necessarily find its way to
> the :"formal" documentation. I think the wiki serves that purpose
> well. It allows users a place to document things that they have
> learned which may not have a good place in the formal
> documentation. So, just because users can't directly update the
> formal documentation I don't think they will feel like second class
> citizens. I think they'd be quite surprised if they could update
> the formal documentation. And actually, I think they would be
> quite pleased and honored if whatever they wrote was moved from the
> wiki into the formal docmentation by an editor.
>
> I really don't see this as much different than how things are with
> the code. Users can write patches and submit them to bugzilla or
> they can post code snippets on the wiki, but they cannot update svn.
One of the things we'd like to get out of this is more user
participation. What I'd like to see is the Daisy site replace the
wiki for documentation purposes. I'd like guest to be able to browse
unfinished and incomplete documentation. I'd like anyone to be able
to write documentation and submit it for publication. The wiki still
has a place, but I've never seen as appropriate way to document things.
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
Re: [VOTE] Consensus about documentation location
Posted by Ralph Goers <Ra...@dslextreme.com>.
Sylvain Wallez wrote:
>
> Same concerns as Ugo. We should IMO document 2.1 and use specially
> labelled sections and pages for what's different in 2.2. We could also
> uses Daisy branches, but I don't think it's a good idea to start a
> multi-branch effort right now.
I agree with this also.
>
>
>> - once the wiki is "processed" (i.e. all documentation is (re)moved), it
>> will only serve as a scratchpad, either for random thoughts/proposals or
>> for users that want to offer documentation but have no editor rights in
>> the Daisy site. I.e. the content of the wiki should be kept as small as
>> possible and deprecated information should be removed as soon as
>> possible.
>>
>>
>
> Same concerns as Leszek: writing docs in the wiki would really make
> non-editors feel like second-class citizen. Additionally to leaving
> comments, we may allow registered users with no particular rights to
> edit documents belonging to a "scratchpad" collection, distinct from
> the main document collection. That will allow us to quickly move
> around good contributions to the main area and also educate editor
> wannabees to the CMS features.
Here I have to disagree with you. I don't think that all the content
that is on the Wiki should necessarily find its way to the :"formal"
documentation. I think the wiki serves that purpose well. It allows
users a place to document things that they have learned which may not
have a good place in the formal documentation. So, just because users
can't directly update the formal documentation I don't think they will
feel like second class citizens. I think they'd be quite surprised if
they could update the formal documentation. And actually, I think they
would be quite pleased and honored if whatever they wrote was moved from
the wiki into the formal docmentation by an editor.
I really don't see this as much different than how things are with the
code. Users can write patches and submit them to bugzilla or they can
post code snippets on the wiki, but they cannot update svn.
>
>
> Sylvain
>
>
Ralph
Re: [VOTE] Consensus about documentation location
Posted by Sylvain Wallez <sy...@apache.org>.
Linden H van der (MI) wrote:
>Guys,
>
>I'm aware that I'm not officially a committer (yet), however, I think it
>will be a good idea to get explicit consensus on where to locate the
>docs and about a rough outline of the future actions.
>
>This is the proposal:
>
>- the current Daisy site at the zones [1] will be the "incubator" for
>the new documentation. I.e. new content is to be entered there.
>
>
+1
>- this documentation is targeted at Cocoon 2.2. This means that we try
>to write version-independent documentation, but when there is a
>difference between 2.1 and 2.2, the documentation will describe 2.2.
>
>
Same concerns as Ugo. We should IMO document 2.1 and use specially
labelled sections and pages for what's different in 2.2. We could also
uses Daisy branches, but I don't think it's a good idea to start a
multi-branch effort right now.
>- the rules for the various roles have been defined already [2]. Note,
>registered guests can leave comments.
>
>
+1
>- this also implies that we stick with Daisy as CMS (and not venture on
>the endless hunt for THE best system/toolset).
>
>
+1
>- all current content in both wiki and "official docs" will be evaluated
>and either deprecated or moved over into the Daisy site.
>
>
+1
>- once the wiki is "processed" (i.e. all documentation is (re)moved), it
>will only serve as a scratchpad, either for random thoughts/proposals or
>for users that want to offer documentation but have no editor rights in
>the Daisy site. I.e. the content of the wiki should be kept as small as
>possible and deprecated information should be removed as soon as
>possible.
>
>
Same concerns as Leszek: writing docs in the wiki would really make
non-editors feel like second-class citizen. Additionally to leaving
comments, we may allow registered users with no particular rights to
edit documents belonging to a "scratchpad" collection, distinct from the
main document collection. That will allow us to quickly move around good
contributions to the main area and also educate editor wannabees to the
CMS features.
>- the current intention is to eventually move the content of the Daisy
>site over to the "official documentation". This is no hard coded rule
>and may be changed later.
>
>
A mod_rewrite rule pointing cocoon.apache.org/docs/ to the cocoon zone
(with an additional mod_cache?) will make publication damn easy :-)
Something important though is to keep a version of the docs in svn at
least for each release, so that we can easily find the docs for a
particular version, and also ship self-contained distros with their
docs. We therefore need a way to dump the content, either in published
form (e.g. with wget on the Daisy frontend) or in source form (by using
the http repository API [1])
Sylvain
[1] http://www.cocoondev.org/daisydocs-1_3/repository/interfaces/21.html
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
Re: [VOTE] Consensus about documentation location
Posted by Reinhard Poetz <re...@apache.org>.
Linden H van der (MI) wrote:
Many thanks for the summary and the vote. I have to admit that I wasn't able to
read all the mails.
> Guys,
>
> I'm aware that I'm not officially a committer (yet), however, I think it
> will be a good idea to get explicit consensus on where to locate the
> docs and about a rough outline of the future actions.
>
> This is the proposal:
>
> - the current Daisy site at the zones [1] will be the "incubator" for
> the new documentation. I.e. new content is to be entered there.
> - this documentation is targeted at Cocoon 2.2. This means that we try
> to write version-independent documentation, but when there is a
> difference between 2.1 and 2.2, the documentation will describe 2.2.
> - the rules for the various roles have been defined already [2]. Note,
> registered guests can leave comments.
> - this also implies that we stick with Daisy as CMS (and not venture on
> the endless hunt for THE best system/toolset).
> - all current content in both wiki and "official docs" will be evaluated
> and either deprecated or moved over into the Daisy site.
> - once the wiki is "processed" (i.e. all documentation is (re)moved), it
> will only serve as a scratchpad, either for random thoughts/proposals or
> for users that want to offer documentation but have no editor rights in
> the Daisy site. I.e. the content of the wiki should be kept as small as
> possible and deprecated information should be removed as soon as
> possible.
+1 for all
> - the current intention is to eventually move the content of the Daisy
> site over to the "official documentation". This is no hard coded rule
> and may be changed later.
Maybe it has already been discussed and then I'm more than happy with a link but
if not, can you explain the process of how our documentation gets published
(http://cocoon.apache.org)? IIUC, cocoon.zones.apache.org/daisy/ is our staging
area and not the official documentation, right?
Another question is the relationship between our generated documentation and the
CMS? Are there any guidelines where we draw the borderline and the integration
process to get one documentation in the end?
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
Re: [VOTE] Consensus about documentation location
Posted by Steven Noels <st...@outerthought.org>.
On 13 Jun 2005, at 16:13, Glen Ezkovich wrote:
> One of the current limitations of Daisy is that we have only 3 roles.
> We need a fourth. Publishers, who make a document official and
> publish it to the main documentation site.
You can have an "official documentation site" with a navtree that is
only editable by a specific role.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source Java & XML An Orixo Member
Read my weblog at http://blogs.cocoondev.org/stevenn/
stevenn at outerthought.org stevenn at apache.org
Re: [VOTE] Consensus about documentation location
Posted by Glen Ezkovich <gl...@hard-bop.com>.
On Jun 13, 2005, at 3:27 AM, Ugo Cei wrote:
> Il giorno 13/giu/05, alle 09:53, Leszek Gawron ha scritto:
>
>
>> Linden H van der (MI) wrote:
>>
>>> - this documentation is targeted at Cocoon 2.2. This means that
>>> we try
>>> to write version-independent documentation, but when there is a
>>> difference between 2.1 and 2.2, the documentation will describe 2.2.
>>>
>
> Why 2.2? I'm afraid (but would love to be proved wrong) that it's
> going to be a while before we have 2.2 out the door. Most users are
> targeting 2.1 and it will be the latest officially released version
> for a long time.
>
> Moreover, many things in 2.2 are not finalized yet, so we'd be
> documenting a moving target.
True. Documenting 2.1 means that by the time I have completed my work
it will be obsolete. Most if the information will be back compatible,
but where there are differences they need to be noted. Documentation
developement usually goes along with code development. One of the
problems with documenting Cocoon is the the activity of the
developers. Once we have some basics in place I can concentrate on
keeping the docs current.
>
>
>>> - this also implies that we stick with Daisy as CMS (and not
>>> venture on
>>> the endless hunt for THE best system/toolset).
>>>
>
> +1
I look at this as an experiment. If it works great if it doesn't we
need to find something else. Right now daisy seems to have some
limitations. We can work around them for now.
>
>
>>> - once the wiki is "processed" (i.e. all documentation is (re)
>>> moved), it
>>> will only serve as a scratchpad, either for random thoughts/
>>> proposals or
>>> for users that want to offer documentation but have no editor
>>> rights in
>>> the Daisy site. I.e. the content of the wiki should be kept as
>>> small as
>>> possible and deprecated information should be removed as soon as
>>> possible.
>>>
>> It would be quite awkward if we have a documentation site but
>> direct users to write their howtos and recipes on empty wiki. It
>> looks like you'd be saying to a common: You're not worth using our
>> CMS. Write some content in our trash-all-there wiki and we will
>> kindly pick it up from there. OR NOT.
One of the current limitations of Daisy is that we have only 3 roles.
We need a fourth. Publishers, who make a document official and
publish it to the main documentation site. Editors, who can view,
edit and comment on the work of others. Writers, who can work only on
their own documents. Guests who can view any document in in any
state. Even unfinished and unacceptable documents have valuable
information.
>>
>> My thought: make user registration at CMS as easy as possible.
>> Grant edit rights in Daisy for some cocoon-documentation-firing-
>> ground site. Pick documents from there and put it into main
>> documentation with ease when the document is mature enough. On
>> wiki users also have to register before editing and that did not
>> make problems.
Registration is a must.
>>
>
> +1
>
>
>>> - the current intention is to eventually move the content of the
>>> Daisy
>>> site over to the "official documentation". This is no hard coded
>>> rule
>>> and may be changed later.
>>>
>> What for really? We will have whole content there (with metadata
>> and comments). Why not make it default cocoon.apache.org? Every
>> new cocoon release would get a static snapshot of online site.
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
Re: [VOTE] Consensus about documentation location
Posted by Ugo Cei <ug...@apache.org>.
Il giorno 13/giu/05, alle 09:53, Leszek Gawron ha scritto:
> Linden H van der (MI) wrote:
>> - this documentation is targeted at Cocoon 2.2. This means that we try
>> to write version-independent documentation, but when there is a
>> difference between 2.1 and 2.2, the documentation will describe 2.2.
Why 2.2? I'm afraid (but would love to be proved wrong) that it's going
to be a while before we have 2.2 out the door. Most users are targeting
2.1 and it will be the latest officially released version for a long
time.
Moreover, many things in 2.2 are not finalized yet, so we'd be
documenting a moving target.
>> - this also implies that we stick with Daisy as CMS (and not venture
>> on
>> the endless hunt for THE best system/toolset).
+1
>> - once the wiki is "processed" (i.e. all documentation is (re)moved),
>> it
>> will only serve as a scratchpad, either for random thoughts/proposals
>> or
>> for users that want to offer documentation but have no editor rights
>> in
>> the Daisy site. I.e. the content of the wiki should be kept as small
>> as
>> possible and deprecated information should be removed as soon as
>> possible.
> It would be quite awkward if we have a documentation site but direct
> users to write their howtos and recipes on empty wiki. It looks like
> you'd be saying to a common: You're not worth using our CMS. Write
> some content in our trash-all-there wiki and we will kindly pick it up
> from there. OR NOT.
>
> My thought: make user registration at CMS as easy as possible. Grant
> edit rights in Daisy for some cocoon-documentation-firing-ground site.
> Pick documents from there and put it into main documentation with ease
> when the document is mature enough. On wiki users also have to
> register before editing and that did not make problems.
+1
>> - the current intention is to eventually move the content of the Daisy
>> site over to the "official documentation". This is no hard coded rule
>> and may be changed later.
> What for really? We will have whole content there (with metadata and
> comments). Why not make it default cocoon.apache.org? Every new cocoon
> release would get a static snapshot of online site.
+1
Ugo
--
Ugo Cei
Tech Blog: http://agylen.com/
Open Source Zone: http://oszone.org/
Wine & Food Blog: http://www.divinocibo.it/
Re: [VOTE] Consensus about documentation location
Posted by Leszek Gawron <lg...@mobilebox.pl>.
Linden H van der (MI) wrote:
> Guys,
>
> I'm aware that I'm not officially a committer (yet), however, I think it
> will be a good idea to get explicit consensus on where to locate the
> docs and about a rough outline of the future actions.
>
> This is the proposal:
>
> - the current Daisy site at the zones [1] will be the "incubator" for
> the new documentation. I.e. new content is to be entered there.
> - this documentation is targeted at Cocoon 2.2. This means that we try
> to write version-independent documentation, but when there is a
> difference between 2.1 and 2.2, the documentation will describe 2.2.
> - the rules for the various roles have been defined already [2]. Note,
> registered guests can leave comments.
> - this also implies that we stick with Daisy as CMS (and not venture on
> the endless hunt for THE best system/toolset).
> - all current content in both wiki and "official docs" will be evaluated
> and either deprecated or moved over into the Daisy site.
> - once the wiki is "processed" (i.e. all documentation is (re)moved), it
> will only serve as a scratchpad, either for random thoughts/proposals or
> for users that want to offer documentation but have no editor rights in
> the Daisy site. I.e. the content of the wiki should be kept as small as
> possible and deprecated information should be removed as soon as
> possible.
It would be quite awkward if we have a documentation site but direct
users to write their howtos and recipes on empty wiki. It looks like
you'd be saying to a common: You're not worth using our CMS. Write some
content in our trash-all-there wiki and we will kindly pick it up from
there. OR NOT.
My thought: make user registration at CMS as easy as possible. Grant
edit rights in Daisy for some cocoon-documentation-firing-ground site.
Pick documents from there and put it into main documentation with ease
when the document is mature enough. On wiki users also have to register
before editing and that did not make problems.
> - the current intention is to eventually move the content of the Daisy
> site over to the "official documentation". This is no hard coded rule
> and may be changed later.
What for really? We will have whole content there (with metadata and
comments). Why not make it default cocoon.apache.org? Every new cocoon
release would get a static snapshot of online site.
--
Leszek Gawron lgawron@mobilebox.pl
IT Manager MobileBox sp. z o.o.
+48 (61) 855 06 67 http://www.mobilebox.pl
mobile: +48 (501) 720 812 fax: +48 (61) 853 29 65