Hi! > Well why don't you check out wiki dictionary effort made > with Cocoon? Perhaps you could help build that > dictionary. http://www.anyware-tech.com/wikiland/
Wiki is an entirely different thing, I believe. > Try not to jump to conclusions about why the state of > documentation is what it currently is. I know the documentation. All of it, except parts that I've already forgot since last reading. > I could add a hundred items to your list. Well, my first point was about simplification of docs creation, and second point was the model to describe things. I can't add those hundreds of items, I just have a few simple and maybe not so obvious ones in mind. I'm normal (i.e. extremely lazy) guy, and I know the way of writing documentation that I would be comfortable with. And since I believe that I'm not alone, I share my ideas about it. I'm not inventing anything, I'm too lazy to do that. :) > When more people come forward to help improve existing > docs, and contribute new docs, then they will improve. > No sooner and no later. I wouldn't be sure about it. I believe in community, but there is enough cases to study - JBoss, Tomcat, Struts. Even the most popular tools usually don't have finished and complete documentation. On the other hand, they have alot of documentation of some kind, and it seems to be a good idea to remember this. If you could create advanced documentation as easy as basic get-started-in-a-minute howtos, there would be more advanced documentation. Document templates (with SCORE installed in form of questions), blanks, any other automation could help if implemented wisely. > There is an effort at Apache Forrest to improve > underlying documentation architecture. If you > don't want to contribute new/revised docs to the Cocoon > project, perhaps you'd be interested in supporting that > project's architectural efforts? Forrest seems to me like an overkill, but I like it and hope it will be finished. I'me not sure that I'll do. I've just wanted to give some hints that could help with a few of major documentation writing-related problems. They are working already here and there. Maybe I'll download Forrest and check it out. > I have built a lot of models in my professional life, and > I'm not sure I would be so brave as to model open source > community dynamics ... ;-) This model is used in therapy. It is the model for changes - that we have, that we want, that we hope to get, that is preventing us from doing that, and that resources could help with that. Problem often goes away right after the client wrote those five points how he thinks about them. One guy we've been discussing recently had used it in rocket-science course and won an award as the writer of the best course in that year. The methods for describing each of points are important to get it working, it has complex origins. It is not a panacea, but a very productive model. I'll just highly recommend to check it out; it is one of those little things that affect the whole way of thinking. If you are interested, I could point where to look for more accurate information, and if you aren't, it would be better to stop at this point. :) [*] > <snip /> > >Symptoms - complex webapp, many documents, big > >hierarchy, difficulties with all this; some > >paragraphs about it. > > I don't agree that a complex webapp is a "symptom" of a > problem. It is part of description of state where the problem arises, where we are starting at. BTW, I've been talking about the _form_ of information presentation, but you are talking about information itself. We are talking about different topics. :) See [*]. > You can have all the structure in the world but you still > need writers. IMHO, the hardest part is writing well. If Check out other open source projects, you can see that kind of documentation complexity and completeness you can expect. _If_ you could provide _good_ guidelines to write those docs and made this process _simple_ (maybe like filling in a blank), then, taking into account growing popularity of cocoon2, you could get those authors. For example, there is many useful info in javadocs, but not in general documentation pages. Maybe it is just because there are defined good guidelines for writing javadocs ? Such rules _must_ be simple, and if we are talking about javadoc writing rules, they are. And there are many javadocs authors out there. :) SCORE is a different beast. It pays off, but requires adoption and understanding. It is for more general docs, not for simple components descriptions. It isn't easy to teach every author about it, but it can help you with writing guidelines, as a minimum. See [*] again. :) > >Resources - use of SoC pattern with Cocoon2 as a tool, > >transforming the hierarchy into tree with no dependency > >between branches; some paragraphs about it. > > What do you mean by hierarchy? I've been talking about general url and site structure and their mappings onto an application structure. This one is far away from the subject. Mikhail --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
