Re: [VOTE] Consensus about documentation location - revised version
Le 13 juin 05, à 17:16, Linden H van der ((MI)) a écrit : Based on some comments I would like to revise the proposal... I'm fine with everything you suggest, just a few comments below. ...- this documentation is targeted at Cocoon 2.1. 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.1. If possible, notes will be added describing the difference in 2.2 or at least that there IS a difference in 2.2... This is fine assuming there is enough energy to complete the task in due time. It might be safer to focus on 2.2, with the aim of being ready when 2.2 is released. But whoever does the job gets to decide, if you guys think the above plan is workable, all the better. FWIW, I will do my best to contribute by reviewing docs, but won't be able to do any or much actual writing in the next few months. ...[Note: API docs provide a special set of generated documentation.. This will hopefully not only be the API docs, but the components docs as well (Generators, Transformers, Serializers etc.). If the cocoon-refdoc project [1] works out as I hope (but I have no idea yet if it will), we'll be able to generate manpage-like docs with essential information, snippets of code, etc., in an XML format suitable for inclusion in Forrest or Daisy docs. Don't hold your breath, but as you indicate it is good to keep that in the back of your minds, and maybe start working on the more general docs first, assuming the details will come from the generated reference docs. -Bertrand [1] http://wiki.apache.org/cocoon/CocoonRefDocProject P.S. Helma, it seems like your mailer is breaking threads sometimes, but not always. For example, [2] starts a new thread although it is obviously a reply to [3]. If it's easy to fix it might be good for our archives. [2] http://marc.theaimsgroup.com/?l=xml-cocoon-devm=111866680601135w=2 [3] http://marc.theaimsgroup.com/?l=xml-cocoon-devm=111866271205873w=2 smime.p7s Description: S/MIME cryptographic signature
RE: [VOTE] Consensus about documentation location - revised version
Hi Bertrand, P.S. Helma, it seems like your mailer is breaking threads sometimes, but not always. For example, [2] starts a new thread although it is obviously a reply to [3]. If it's easy to fix it might be good for our archives. [2] http://marc.theaimsgroup.com/?l=xml-cocoon-devm=111866680601135w=2 [3] http://marc.theaimsgroup.com/?l=xml-cocoon-devm=111866271205873w=2 I have no idea. I'm using Outlook connecting to an Exchange server. I changed the header myself, to reflect the content. So tell me what I should do/don't do. Bye, Helma
Re: [VOTE] Consensus about documentation location - revised version
Linden H van der (MI) wrote: Hi Bertrand, P.S. Helma, it seems like your mailer is breaking threads sometimes, but not always. For example, [2] starts a new thread although it is obviously a reply to [3]. If it's easy to fix it might be good for our archives. [2] http://marc.theaimsgroup.com/?l=xml-cocoon-devm=111866680601135w=2 [3] http://marc.theaimsgroup.com/?l=xml-cocoon-devm=111866271205873w=2 I have no idea. I'm using Outlook connecting to an Exchange server. I changed the header myself, to reflect the content. So tell me what I should do/don't do. Outlook doesn't send the correct headers in order to track who replied to whom. This was discussed a while ago here: http://marc.theaimsgroup.com/?l=xml-cocoon-devm=107548477026275w=2 I'd encourage you to start using a different mail client such as Mozilla/Thunderbird because it *does* make it a lot easier to follow the discussions. Perhaps it should be mentioned on our site that mailing lists are best participated in using a mailer that does not break the thread view, just as we ask people to send their messages in plain text for example. -- Unico
[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
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
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 [EMAIL PROTECTED] 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
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/ smime.p7s Description: S/MIME cryptographic signature
Re: [VOTE] Consensus about documentation location
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 WallezAnyware Technologies http://apache.org/~sylvainhttp://anyware-tech.com Apache Software Foundation Member Research Technology Director
RE: [VOTE] Consensus about documentation location
Reinhard, 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? AFAIU there is a Daisy-to-Forrest plugin available now or any time soon that could do the trick. 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? Please help out, what generated documentation do you mean? Are you referring to documentation embedded in Java docs? I.e. API docs? Bye, Helma
Re: [VOTE] Consensus about documentation location
Linden H van der (MI) wrote:
Reinhard,
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?
AFAIU there is a Daisy-to-Forrest plugin available now or any time soon
that could do the trick.
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?
Please help out, what generated documentation do you mean? Are you
referring to documentation embedded in Java docs? I.e. API docs?
yes, the usual javadocs, the page generated out of trunk/lib/jars.xml and the
pages generated out of the javadocs of sitemap components. Some auto-generated
documentation for Cocoon Forms also makes sense or is IMHO the only chance to
keep the docs consistent with the code.
Additionally we will have to work out how this relates to the cocoon-refdoc
project Bertrand is mentoring.
--
Reinhard Pötz Independent Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
RE: generated docs (was: [VOTE] Consensus about documentation location)
yes, the usual javadocs, the page generated out of trunk/lib/jars.xml and the pages generated out of the javadocs of sitemap components. To me this is API docs and serve a special purpose. _I_ would be perfectly happy if they were in an accessible place, with links to it from the ordinary docs, but not part of the docs themselves. Some auto-generated documentation for Cocoon Forms also makes sense or is IMHO Hmm, I'm lost here, what auto-generated documentation for CForms do you mean? the only chance to keep the docs consistent with the code. I have thought this too earlier on, but apart from the few exceptions, most code-writers don't write (good) documentation. This should be discussed further, but I'm inclined to have programmers write the code and add enough java docs to explain the reason and usage for the class/component. A person with more documentation skills can elaborate this information and add it to the ordinary docs. Additionally we will have to work out how this relates to the cocoon-refdoc project Bertrand is mentoring. TDB. Bye, Helma
Re: [VOTE] Consensus about documentation location
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
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 [EMAIL PROTECTED] 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
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 - revised version
Based on some comments I would like to revise the proposal. Let's focus first on what info goes where and what the general direction will be. As things progress, we can focus on explicit processes and, given the current discussion, the roles/rights. - 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.1. 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.1. If possible, notes will be added describing the difference in 2.2 or at least that there IS a difference in 2.2. [Note: I was under the impression that 2.2 was already close to a release-able state] - 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. I.e. reducing the wiki to random thoughts and proposals. - it should be possible to easily add new documentation contributions to the Daisy site, although it should be separated from the current site so editors/publishers can review the information before adding it to the documentation. This is not a vote of mistrust, but rather an effort to keep the documentation under control. AND, as stated: guest contributors may feel very proud if their contribution is incorporated in the official docs. I know I was proud when my first patch was picked up and committed. [Note: this means that a separate site with different roles/rights has to be set up] - we should make sure that we end up with only one (virtual) documentation site, whatever the format/system etc. will be. The current intention is to eventually move the content of the Daisy site over to the official documentation. [Note: API docs provide a special set of generated documentation. They serve a different purpose than the ordinary documentation. To me, at least for now, it is sufficient if there is an easy link from the ordinary docs to the API docs, even if they reside in a different location.] - Extraction of current state for inclusion in a release should be possible. AFAIU there is a Daisy-to-Forrest plugin available (soon). [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
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 Noelshttp://outerthought.org/ Outerthought - Open Source Java XMLAn Orixo Member Read my weblog athttp://blogs.cocoondev.org/stevenn/ stevenn at outerthought.orgstevenn at apache.org
Re: [VOTE] Consensus about documentation location - revised version
Linden H van der (MI) wrote: Based on some comments I would like to revise the proposal. Let's focus first on what info goes where and what the general direction will be. As things progress, we can focus on explicit processes and, given the current discussion, the roles/rights. - 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.1. 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.1. If possible, notes will be added describing the difference in 2.2 or at least that there IS a difference in 2.2. [Note: I was under the impression that 2.2 was already close to a release-able state] - 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. I.e. reducing the wiki to random thoughts and proposals. - it should be possible to easily add new documentation contributions to the Daisy site, although it should be separated from the current site so editors/publishers can review the information before adding it to the documentation. This is not a vote of mistrust, but rather an effort to keep the documentation under control. AND, as stated: guest contributors may feel very proud if their contribution is incorporated in the official docs. I know I was proud when my first patch was picked up and committed. [Note: this means that a separate site with different roles/rights has to be set up] - we should make sure that we end up with only one (virtual) documentation site, whatever the format/system etc. will be. The current intention is to eventually move the content of the Daisy site over to the official documentation. [Note: API docs provide a special set of generated documentation. They serve a different purpose than the ordinary documentation. To me, at least for now, it is sufficient if there is an easy link from the ordinary docs to the API docs, even if they reside in a different location.] - Extraction of current state for inclusion in a release should be possible. AFAIU there is a Daisy-to-Forrest plugin available (soon). [1] http://cocoon.zones.apache.org/daisy/cocooninaction/4.html [2] http://www.mail-archive.com/dev@cocoon.apache.org/msg31807.html Bye, Helma +1
Re: [VOTE] Consensus about documentation location
Reinhard Poetz wrote: Linden H van der (MI) wrote: Reinhard, 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? AFAIU there is a Daisy-to-Forrest plugin available now or any time soon that could do the trick. Yes. There is a prototype in use right now, all this does is include an HTML page from the daisy-wiki in a Forrest site. The next version will have many new features, such as: - tight integration with the new publishing API in Daisy 1.3M2 - use of the locationmap in Forrest to allow reader URLs and editor URLs to be completely independant - embedding the Daisy edit page within the Forrest site (in a dynamic envronment) - translation of Daisy navigation documents into Forrest site.xml documents (incidentally, Forrest has just started working with Lenya to experiment with Lenya as an alternative CMS. I am not advocating Cocoon switch to Lenya, just making you aware that there is an alternative. Development on the Daisy plugin will continue as I need it for my own purposes.) 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? Please help out, what generated documentation do you mean? Are you referring to documentation embedded in Java docs? I.e. API docs? yes, the usual javadocs, the page generated out of trunk/lib/jars.xml and the pages generated out of the javadocs of sitemap components. Some auto-generated documentation for Cocoon Forms also makes sense or is IMHO the only chance to keep the docs consistent with the code. The use of Forrest as a publishing engine for your CMS site allows for the seamless integration of autogenerated docs. For example, define a Forrest site.xml with all the requrie links to auto generated docs, such as javadocs, and embed one or more Daisy navigation documents within this site.xml to include the human edited docs. Additionally we will have to work out how this relates to the cocoon-refdoc project Bertrand is mentoring. I'm a co-mentor on that project. The reason I volunteered was entirely because of this kind of issue, it is my intention to integrate the outputs of this project into a plugin for Forrest managed sites. Ross
Re: [VOTE] Consensus about documentation location
Ross Gardler wrote:
Reinhard Poetz wrote:
Linden H van der (MI) wrote:
Reinhard,
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?
AFAIU there is a Daisy-to-Forrest plugin available now or any time soon
that could do the trick.
Yes. There is a prototype in use right now, all this does is include an
HTML page from the daisy-wiki in a Forrest site. The next version will
have many new features, such as:
- tight integration with the new publishing API in Daisy 1.3M2
- use of the locationmap in Forrest to allow reader URLs and editor URLs
to be completely independant
- embedding the Daisy edit page within the Forrest site (in a dynamic
envronment)
- translation of Daisy navigation documents into Forrest site.xml documents
(incidentally, Forrest has just started working with Lenya to experiment
with Lenya as an alternative CMS. I am not advocating Cocoon switch to
Lenya, just making you aware that there is an alternative. Development
on the Daisy plugin will continue as I need it for my own purposes.)
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?
Please help out, what generated documentation do you mean? Are you
referring to documentation embedded in Java docs? I.e. API docs?
yes, the usual javadocs, the page generated out of trunk/lib/jars.xml
and the pages generated out of the javadocs of sitemap components.
Some auto-generated documentation for Cocoon Forms also makes sense or
is IMHO the only chance to keep the docs consistent with the code.
The use of Forrest as a publishing engine for your CMS site allows for
the seamless integration of autogenerated docs. For example, define a
Forrest site.xml with all the requrie links to auto generated docs, such
as javadocs, and embed one or more Daisy navigation documents within
this site.xml to include the human edited docs.
Additionally we will have to work out how this relates to the
cocoon-refdoc project Bertrand is mentoring.
I'm a co-mentor on that project. The reason I volunteered was entirely
because of this kind of issue, it is my intention to integrate the
outputs of this project into a plugin for Forrest managed sites.
great!!!
--
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
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 - revised version
On Jun 13, 2005, at 10:16 AM, Linden H van der (MI) wrote: Based on some comments I would like to revise the proposal. Let's focus first on what info goes where and what the general direction will be. As things progress, we can focus on explicit processes and, given the current discussion, the roles/rights. - 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.1. 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.1. If possible, notes will be added describing the difference in 2.2 or at least that there IS a difference in 2.2. [Note: I was under the impression that 2.2 was already close to a release-able state] - 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. I.e. reducing the wiki to random thoughts and proposals. - it should be possible to easily add new documentation contributions to the Daisy site, although it should be separated from the current site so editors/publishers can review the information before adding it to the documentation. This is not a vote of mistrust, but rather an effort to keep the documentation under control. AND, as stated: guest contributors may feel very proud if their contribution is incorporated in the official docs. I know I was proud when my first patch was picked up and committed. [Note: this means that a separate site with different roles/rights has to be set up] - we should make sure that we end up with only one (virtual) documentation site, whatever the format/system etc. will be. The current intention is to eventually move the content of the Daisy site over to the official documentation. [Note: API docs provide a special set of generated documentation. They serve a different purpose than the ordinary documentation. To me, at least for now, it is sufficient if there is an easy link from the ordinary docs to the API docs, even if they reside in a different location.] - Extraction of current state for inclusion in a release should be possible. AFAIU there is a Daisy-to-Forrest plugin available (soon). [1] http://cocoon.zones.apache.org/daisy/cocooninaction/4.html [2] http://www.mail-archive.com/dev@cocoon.apache.org/msg31807.html Bye, Helma My non-voting +1 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
