> I spent last weekend going over Cocoon's documentation, various > threads concerning it and proposed TOCs. I came away with the feeling > that Cocoon's documentation is written by experienced Cocoon > developers for experienced Cocoon developers. The only thing Cocoon's > documentation should assume is that a user is familiar with XML and > XSLT. If they want to use flow the documentation needs to assume that > they have some familiarity with javascript and/or Java. Its similar > for each aspect of Cocoon. Assume only enough to go forward with out > having to explain things outside of Cocoon.
Obviously we share exactly the same concerns. I don't know if you had a look at my documentation workflow proposal (http://www.planetcocoon.com/node/2079) but as you'll see, everything is made to put readers needs and assumptions about their knowledge at the center of our documentation writing process. And I totally agree with you : current documentation is mainly written by developers for other developers and that's precisely one of the main reasons why we started our initiative on Planet Cocoon, to create a real *user* documentation writing platform. > I have an email that I have been working on since Monday with an > outline of how I was planing to proceed with writing new > documentation. Key aspects are that we need to have separate > documentation for users and developers and that the user > documentation needs to assume as little as possible about the users > experience. Hopefully, I will edit down to a few paragraphs and send > it this weekend. I'm looking forward to hear your ideas. Maybe it could be the occasion to join our efforts on Planet Cocoon. That's how I joined Mark in this initiative, you could join us. > In the meantime you might want to consider targeting your > documentation for the most junior and least skilled website developer > in your company. Better yet, a 1st year student. Once more we'll even do better than that : we are going to setup a documentation request mechanism so that people can give details about what they want to know AND what they already know. That way we'll have an objective view about what we can assume or not when writing documentation, and eventually make Cocoon more accessible. > I mean all this in the most constructive way. Hopefully we will be > able to collaborate over the next 4 weeks and get a good start on > rewriting these docs. That would be great ! Cheers -- Sebastien ARBOGAST
