RE: Documentation TOC started
> I mean that our core documentation, i.e. the xdocs and the key Wiki > pages, should be be written by this community and should be the > definitive view on the topic. Aha, that's a clear point. Especially the latter. I currently have a feeling that definitive views on several topics are changing (e.g. flow vs actions, jx vs xsp), it would be nice to get certain things down "in writing" to make it easier to decide on which "learning curve" to take. > In general we should not make links to outside documentation because > we have absolutely no control over what they say about Cocoon. They > might have some good statements then a heap of misguided statements. > We would be leading the users astray because our core documentation > would appear to recommend that document as some authority. True, on the other hand I think that a good product can defend itself and linking to "the enemy" might just as well be an indication of that. Sure, this shouldn't be included in the core documents, but a Wiki page with such links (e.g. the TSS article lately AS WELL AS the discussions about it, both here and on the TSS article reviews) might prove to be just enough to newbies to decide to start with Cocoon or to drop it before getting into it. > Besides that, constantly changing URLs and dead links are too hard > to manage over time. Right, although I find that less irritating in a Wiki page than in the xdocs. > > I was thinking along this line: > > - references to external URLs that explain "add-ins" for > Cocoon, e.g. the > > flowscript debugger, the Sunbow plugins for Eclipse etc. > > - references to blog entries which explain some otherwise > hard to find info. > > - references to mail archives. > > - references to articles on Cocoon (e.g. the TSS article lately) > > - anything else I've forgotten > > > > The latter 2 are stuff for the Wiki page. > > For the first 3 I'm thinking of getting in touch with the > original authors > > and ask permission to include/rewrite the information and > include it in the > > Cocoon xdoc itself. When components are involved, links are > included to the > > authors pages for more info and downloads. > > It is the external links that can lead to problems. Yes, but how to include information on e.g. the sunbow plugins for Eclipse? Either the you include the entire text in the xdocs (with the authors' permission of course), but are still left with links to the actual code, or you need to refer to Wiki pages (which are currently changing URL :-) ) which contain such information. > Sure. You are "preaching to the converted" on cocoon-dev :-) Sorry, I'm used to the male technical geeks that write better code than their native language. And usually consider code enough documentation anyway. ;-) Bye, Helma
RE: Documentation TOC started
H.vanderLinden wrote: > David Crossley wrote: > > > > ...This is then orthogonal to the total > > restructuring of the xdocs, which was shelved until 2.2 > > because it would otherwise break our URL space. > > AHA. That explains the "complete radio silence" when it comes to updating > the documentation. :-) No, not really that. Documentation can be enhanced totally independent of any restructure. I am lost in attempting to understand why very little contributions to existing documentation are being made by the community. Quite a few of us have attempted to deal with the documentation. Don't let that discourage you ... keep on. > > I would certainly like to see this ToC cater for the > > anticipated "Reference documentation" (cannot find old dev@ > > or old docs@ discussion yet). > > What exactly do you mean by "reference documentation"? To me it's a mixture > of JavaDocs + extra explanation + textual examples and maybe even a live > working example in the "samples" section. That is right, something along those lines. Automatically generated by extracting certain Javadoc tags and supplementing with other info. There are discussions about it in the dev or initial docs mail archive. > > One thing that we had discussed about Cocoon core xdocs > > documentation was that it should not appear to sanctify any > > external documentation, because there is some stuff out there > > that we may not be happy with and where do we draw the line. > > Hmm, maybe it's simply my understanding of English, but I don't really > understand what you mean here. Do you mean that "no" external reference > should be included or "all"? I mean that our core documentation, i.e. the xdocs and the key Wiki pages, should be be written by this community and should be the definitive view on the topic. In general we should not make links to outside documentation because we have absolutely no control over what they say about Cocoon. They might have some good statements then a heap of misguided statements. We would be leading the users astray because our core documentation would appear to recommend that document as some authority. Besides that, constantly changing URLs and dead links are too hard to manage over time. I think the best solution is to have very few references to external documentation about Cocoon. We would have a set of community-supported Wiki pages for that. > I was thinking along this line: > - references to external URLs that explain "add-ins" for Cocoon, e.g. the > flowscript debugger, the Sunbow plugins for Eclipse etc. > - references to blog entries which explain some otherwise hard to find info. > - references to mail archives. > - references to articles on Cocoon (e.g. the TSS article lately) > - anything else I've forgotten > > The latter 2 are stuff for the Wiki page. > For the first 3 I'm thinking of getting in touch with the original authors > and ask permission to include/rewrite the information and include it in the > Cocoon xdoc itself. When components are involved, links are included to the > authors pages for more info and downloads. It is the external links that can lead to problems. > This would be my option, because I've experienced myself numerous times > where I "searched myself colorblind" to find information on a certain topic, > only to stumble across it in a totally unrelated description or after much > mailing back and forth on the mailing list. > For me a good product has 2 main aspects: 1. It works more or less out of > the box and works as expected, 2. If not, there is a good manual where I can > look (most) things up. From my POV Cocoon has (1), but lacks (2) in the sens > that the information is probably "somewhere", but it cannot be found easily. Sure. You are "preaching to the converted" on cocoon-dev :-) --David > > Also we do not want to get into URL management and dead > > links. So yes, a separate Wiki page sounds better. > > My idea. > > > There is one aspect that i am still not clear about. Do you > > envisage that this ToC itself would become an xdoc? I hope so. > > Yes. Every book needs a ToC, an ebook even more so. In fact, it would also > need an index. (sigh, even more work :-) ). > > > If so, then that is why i would like it to be free from > > references to external cocoon-related stuff. > > Ok, I'll start a new Wiki page. > > Bye, Helma
Re: Documentation TOC started
Le 16 avr. 04, à 14:40, [EMAIL PROTECTED] a écrit : ...Ultimately you're right and the ToC should be generated, but for now I want to use it as an inventory for what's available, what's missing and in short: how much work is ahead. :-) Fine, thanks for the clarification! -Bertrand
RE: Documentation TOC started
Hi, > I dont' want to stop or slow down your most welcome > initiative, but how > about *generating* the TOC from metadata (that would need to be added > to the docs, see [1]), instead of having a static TOC? Ultimately you're right and the ToC should be generated, but for now I want to use it as an inventory for what's available, what's missing and in short: how much work is ahead. :-) Bye, Helma
Re: Documentation TOC started
Le 16 avr. 04, à 13:11, [EMAIL PROTECTED] a écrit : ...Yes I noticed on the wiki, my idea exactly to merge them, although my plans with the ToC are more "grand". As explained in another message, my goal is to get to an ebook kind of documentation I dont' want to stop or slow down your most welcome initiative, but how about *generating* the TOC from metadata (that would need to be added to the docs, see [1]), instead of having a static TOC? -Bertrand [1] http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=108057364416305&w=2
RE: Documentation TOC started
Hi Bertrand, > Sorry about that. I guess some of us are in a more or less burnout > state about the docs (I am). Hmm, it's more difficult to write good documentation than write good code. > There have been many discussions about how to improve the docs, many > real good ideas flying around (moving everything to the wiki, > generating reference docs from code, generating table of > contents from > keywords in docs, etc), but until now not much has been done in terms > of restructuring / making the docs more accessible. Many talks, not > much action (I'm as guilty as anyone, not pointing fingers). Well, in my opinion a ToC is about the only thing that can be "generated" when talking about documentation. All the rest is more craftmanship from a writers POV than from a developers POV. Sure, javadoc in the code surely helps, but it's often too limited. > So yes, your TOC initiative is very welcome! Thanks. > A while ago I started writing "documentation tracks" [1]. Would a > merging of the two concepts (your TOC and these tracks) be useful? I > think it's about the same idea: provide a roadmap into the docs. Yes I noticed on the wiki, my idea exactly to merge them, although my plans with the ToC are more "grand". As explained in another message, my goal is to get to an ebook kind of documentation. At first, I'll include the pages in the ToC (or you can do that yourself if you feel like), in later steps I suppose we have to integrate them into the documentation. The idea is great though. Bye, Helma
Re: Documentation TOC started
Hi Helma, ...AHA. That explains the "complete radio silence" when it comes to updating the documentation. :-) ... Sorry about that. I guess some of us are in a more or less burnout state about the docs (I am). There have been many discussions about how to improve the docs, many real good ideas flying around (moving everything to the wiki, generating reference docs from code, generating table of contents from keywords in docs, etc), but until now not much has been done in terms of restructuring / making the docs more accessible. Many talks, not much action (I'm as guilty as anyone, not pointing fingers). So yes, your TOC initiative is very welcome! A while ago I started writing "documentation tracks" [1]. Would a merging of the two concepts (your TOC and these tracks) be useful? I think it's about the same idea: provide a roadmap into the docs. -Bertrand [1] http://cocoon.apache.org/2.1/tracks/index.html
RE: Documentation TOC started
Hi David, > > section. My ultimate goal is an ebook kind of documentation. > > Great idea. This is then orthogonal to the total > restructuring of the xdocs, which was shelved until 2.2 > because it would otherwise break our URL space. AHA. That explains the "complete radio silence" when it comes to updating the documentation. :-) > I would certainly like to see this ToC cater for the > anticipated "Reference documentation" (cannot find old dev@ > or old docs@ discussion yet). What exactly do you mean by "reference documentation"? To me it's a mixture of JavaDocs + extra explanation + textual examples and maybe even a live working example in the "samples" section. > > Part of the documentation in my view is also a section on > "Cocoon info > > in the rest of the world", although this might very well be a wiki > > page. > > Well i think that we should start that now, then keep > this page clean. Ok. > One thing that we had discussed about Cocoon core xdocs > documentation was that it should not appear to sanctify any > external documentation, because there is some stuff out there > that we may not be happy with and where do we draw the line. Hmm, maybe it's simply my understanding of English, but I don't really understand what you mean here. Do you mean that "no" external reference should be included or "all"? I was thinking along this line: - references to external URLs that explain "add-ins" for Cocoon, e.g. the flowscript debugger, the Sunbow plugins for Eclipse etc. - references to blog entries which explain some otherwise hard to find info. - references to mail archives. - references to articles on Cocoon (e.g. the TSS article lately) - anything else I've forgotten The latter 2 are stuff for the Wiki page. For the first 3 I'm thinking of getting in touch with the original authors and ask permission to include/rewrite the information and include it in the Cocoon xdoc itself. When components are involved, links are included to the authors pages for more info and downloads. This would be my option, because I've experienced myself numerous times where I "searched myself colorblind" to find information on a certain topic, only to stumble across it in a totally unrelated description or after much mailing back and forth on the mailing list. For me a good product has 2 main aspects: 1. It works more or less out of the box and works as expected, 2. If not, there is a good manual where I can look (most) things up. From my POV Cocoon has (1), but lacks (2) in the sens that the information is probably "somewhere", but it cannot be found easily. > Also we do not want to get into URL management and dead > links. So yes, a separate Wiki page sounds better. My idea. > There is one aspect that i am still not clear about. Do you > envisage that this ToC itself would become an xdoc? I hope Yes. Every book needs a ToC, an ebook even more so. In fact, it would also need an index. (sigh, even more work :-) ). > so. If so, then that is why i would like it to be free from > references to external cocoon-related stuff. Ok, I'll start a new Wiki page. Bye, Helma
RE: Documentation TOC started
H.vanderLinden wrote: > David Crossley wrote: > > Good idea and i admire your enthusiasm. > > Thanks. > > > You will see my additions to that page were i tried to ensure > > Yes I noticed. > > > that it only links to local Cocoon documentation. Already i see > > that people are not heeding that, and linking off to all sorts of > > remote stuff. It may end up just being a jump page to everything. > > Well, at first I like this page to be a kind of inventory to available and > missing documentation. After that I think it needs to be structured, with > some pages possibly rewritten and end up in the xdoc section. My ultimate > goal is an ebook kind of documentation. Great idea. This is then orthogonal to the total restructuring of the xdocs, which was shelved until 2.2 because it would otherwise break our URL space. I would certainly like to see this ToC cater for the anticipated "Reference documentation" (cannot find old dev@ or old docs@ discussion yet). > Part of the documentation in my view is also a section on "Cocoon info in > the rest of the world", although this might very well be a wiki page. Well i think that we should start that now, then keep this page clean. One thing that we had discussed about Cocoon core xdocs documentation was that it should not appear to sanctify any external documentation, because there is some stuff out there that we may not be happy with and where do we draw the line. Also we do not want to get into URL management and dead links. So yes, a separate Wiki page sounds better. > > Please also scan the dev@ and the old docs@ archives. > > This TOC topic has been discussed and commenced many times. > > :-) I'm sure it has, I'll have a look. > > > I think that such pages will need very clear intentions and > > monitoring to keep on track. > > Is the above clear enough? That helps a lot thanks. There is one aspect that i am still not clear about. Do you envisage that this ToC itself would become an xdoc? I hope so. If so, then that is why i would like it to be free from references to external cocoon-related stuff. --David
RE: Documentation TOC started
Hi David, > Good idea and i admire your enthusiasm. Thanks. > You will see my additions to that page were i tried to ensure Yes I noticed. > that it only links to local Cocoon documentation. Already i see > that people are not heeding that, and linking off to all sorts of > remote stuff. It may end up just being a jump page to everything. Well, at first I like this page to be a kind of inventory to available and missing documentation. After that I think it needs to be structured, with some pages possibly rewritten and end up in the xdoc section. My ultimate goal is an ebook kind of documentation. Part of the documentation in my view is also a section on "Cocoon info in the rest of the world", although this might very well be a wiki page. > Please also scan the dev@ and the old docs@ archives. > This TOC topic has been discussed and commenced many times. :-) I'm sure it has, I'll have a look. > I think that such pages will need very clear intentions and > monitoring to keep on track. Is the above clear enough? Bye, Helma
Re: Documentation TOC started
Helma.vanderLinden wrote: > Guys (and girls), > > I want to structure all the documentation about Cocoon in the Wiki and the > xdocs. I've started small by setting up a Wiki page > http://wiki.cocoondev.org/Wiki.jsp?page=Cocoon215TOC which should become a > Table of Contents into documentation geared to Cocoon 2.1.5 and future > versions. Good idea and i admire your enthusiasm. You will see my additions to that page were i tried to ensure that it only links to local Cocoon documentation. Already i see that people are not heeding that, and linking off to all sorts of remote stuff. It may end up just being a jump page to everything. > At first I want to fill this page with links to existing Wiki and xdoc > pages, after that missing pages should be added and outdated pages updated > or rewritten. > > The first draft of this TOC is far from complete, so I'd like you all to > take a quick look at the wiki page and add missing items and sections. Please also scan the dev@ and the old docs@ archives. This TOC topic has been discussed and commenced many times. I think that such pages will need very clear intentions and monitoring to keep on track. --David
RE: Documentation TOC started
Hi, > Awesome, Helma! You made my day. :-) > One thing I was thinking about: Should we try to move the existing > "real" docs to the Wiki, to let us revise them easier? I > think we would > need something to convert the docs format to Wiki and back easily. >From what I've seen, the formatting possibilities of the Wiki are less than those of the "real" docs. So I think that some formatting will be lost in the conversion and that might make it more difficult to understand/update. > Chaperon should allow us to go from Wiki -> Docs, but it's a > matter of having the time to actually do it. Right, so let's take "babysteps" in this and start with linking first. If we're going to update pages, I'd rather do it by hand one by one. In that case if time runs out there is SOMETHING, rather than a lot of work that can be thrown out because it never reached the point of getting updated. Bye, Helma
Re: Documentation TOC started
[EMAIL PROTECTED] wrote: Guys (and girls), I want to structure all the documentation about Cocoon in the Wiki and the xdocs. I've started small by setting up a Wiki page http://wiki.cocoondev.org/Wiki.jsp?page=Cocoon215TOC which should become a Table of Contents into documentation geared to Cocoon 2.1.5 and future versions. At first I want to fill this page with links to existing Wiki and xdoc pages, after that missing pages should be added and outdated pages updated or rewritten. The first draft of this TOC is far from complete, so I'd like you all to take a quick look at the wiki page and add missing items and sections. Awesome, Helma! I was rolling around the idea of how to reorganize and rewrite the docs the other day... I appreciate you taking the time to do this. One thing I was thinking about: Should we try to move the existing "real" docs to the Wiki, to let us revise them easier? I think we would need something to convert the docs format to Wiki and back easily. Chaperon should allow us to go from Wiki -> Docs, but it's a matter of having the time to actually do it. Thanks. Bye, Helma Thoughts? Tony
