The discussion on where the DOCS should be discussed is burning a lot of energy which could be used to build the DOCS.
Yes, newbie friendly documentation is a must for Cocoon's survival. I am also having difficulties helping people get up to speed on simple problems, because I can't quickly refer them to a rich documentation source. Dianna, can you please start a separate thread and begin to build the documentation itself. Is there a easy way to create a docs list and have a server side robot automatically prepend [DOCS] to the subject and forward each message to the users and dev list? I am +1 if this is doable. Cheers, Ivelin ----- Original Message ----- From: "Stefano Mazzocchi" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Thursday, May 09, 2002 7:30 AM Subject: Re: [vote] cocoon-docs > Diana Shannon wrote: > > > > How will that differ from the dev list? > > > > The dev list is about developing first-rate software. Stefano argues > > passionately that software design solutions should not being driven by > > implementation difficulties. Right now, cocoon docs suffer because they > > are not "implemented" in response to a well-articulated design goal > > based on "real world" needs of users. If you developers only knew just > > how *hard* it is to use Cocoon with the existing document set. Just > > yesterday, I was pulling my hair out, working on a sitemap from scratch, > > trying to remember the exact configuration detail of a specific pipeline > > component I needed. I had to dig through five different pages to find > > the information I needed. It's just too frustrating, even for a > > motivated user. > > Oh, I exactly know how hard this is, but the difference is that we *DO* > have great docs for Cocoon: the code itself. :) > > I have to admit that normally I don't even touch the Cocoon > documentation (not even javadocs) and go straight to the source files... > this community is probably formed by people who are all able/willing to > do that. The user community is formed by people who don't want to do it. > > And I'm totally with Diana that we should make life easier for those who > don't want to follow our development mode. So I'll make an effort *not* > to touch the source code but to try to start from the docs. > > I suggest all of you to do the same and I'm pretty sure much more > documentation itches will emerge for you to scratch. > > > A doc-list will be better able to direct document development effort > > because it will be the product of more concerns. I'm not talking only > > about authors and editors but also trainers, educators, publishing > > folks, content experts -- all of them Cocoon users! I know many > > developers care about documentation, but limiting the discussion to a > > list that is dominated by development concerns isn't "healthy." To > > extend the recent RT evolution analogy, I'm trying to increase the > > diversity of the contributing gene pool, not wait for developers to > > genetically sprout documentation expertise. Remember, evolution of a > > species occurs over huge time frames (relative to individual > > lifetimes). We have a diverse community of users we haven't begun to > > engage in the process. They need a place where they can express their > > views, without being accused of making "stupid" posts. A doc-list will > > provide a more balanced points of view, and it won't be perceived as a > > second-class citizen. It will articulate holistic design goals for docs, > > and work out effective implementation details. I think it will also help > > to simplify the submission/review process. > > I'm willing to try this approach. I do believe it's entirely possible > that very few people will subscribe there and many developers will > continue to follow their habits, but community dynamics (like evolution) > are extremely hard to forecast (due to their intrinsic non-linear > nature). > > Since what we have today doesn't work, I think we should do something > different and what Diana proposes might not be a perfect solution but > it's definately a new step and I trust her judgement on that. > > > > If everyone on dev should read doc, too, and I assume people on the > > > doc list should monitor dev as well, as ideas are discussed and > > > announced (sometimes even explained ;-) on the dev list. What > > > difference would it make? > > > > I don't agree that all doc list subscribers will want to (or should have > > to) monitor the dev list. > > Yes, and the opposite, but I think that we should try to give the > ability for each person to focus on what they care. SoC at the community > level. > > > Some are going to pop in and out for very > > brief periods of time, for input on documentation they are authoring, > > period. Look, documentation folks are a different breed of people. We > > care as much about elegant, effective prose as you do about elegant, > > effective code. We get the biggest thrill, seeing the "light turn on" in > > the eyes of a struggling learner/reader. You need *both* efforts to > > sustain Cocoon's growth at this point in time, and you need to address > > both needs equally with separate lists. IMHO the quality of documents is > > holding back Cocoon's growth. I take *great* issue with the notion that > > incremental development is inherently sustainable. Sustainable growth is > > a result of *not* outstripping your resource base, in this case, users > > and developers alike. A major negative feedback loop kicks in when > > user's can't keep up with the pace of change -- however incremental -- > > particularly when documentation is poor. Just because change is > > incremental, the result of many small efforts, doesn't mean the > > resulting "impact" is small. Think about population growth problems. > > Lots of people incrementally adding one child at a time can easily > > create a major sustainability problem. > > > > > What about using Wiki pages for documentation? > > > > One of my medium priorities on todo-doc.xml is to explore wiki for QA > > and maintenance purposes. I *still* believe you need a more centered, > > somewhat structured effort to create enough "meat" to help even wiki > > efforts succeed. > > Agreed. Look at the PHP docs (which are very nicely done, IMO): they do > have user comments at the end of their pages, but the do have structured > and edited pages first. > > > I think there's a tendency to throw technological fixes > > at every problem. > > Ah, gosh, I revote +1 on the cocoon-docs list (and to your commit > access) just for this single sentence right here. > > And now, excuse me, but I have to kick some asses. > > -- > Stefano Mazzocchi One must still have chaos in oneself to be > able to give birth to a dancing star. > <[EMAIL PROTECTED]> Friedrich Nietzsche > -------------------------------------------------------------------- > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, email: [EMAIL PROTECTED] > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
