> I don't mean the docs have to be made up of small chunks, but it must > be possible to do useful work on them in small amounts of time (which > is perfectly possible with the 2.2 docs system).
Let's think in terms of network architecture and layers. I personally think that what Reinhard and Upayavira with the 2.2docs system is perfect as a basis, as a low level architecture layer to work upon. But as I see it, it's still too far from the potential documentation writer, especially for that kind of global "high-level" tutorial we would like to build here. I mean for you and me and the vast majority of Cocoon developers, we know how to check out sources from SVN repository, we know what forrest is and we know how to edit HTML files. As for communication, we can surely use mailing list and wiki. So when you are a developer, you can write documentation. But is the assumption true the other way round ? I don't think so. I really don't think that one should need all of that to write documentation and to collaborate with others. It's necessary but it's too low-level, so for newcomers it is discouraging, and for us it totally lacks productivity. That's what I would like to try with this initiative : build a quick overlayer to make the link between potential documentation writers and the development architecture. This layer will provide all the communication and collaboration services that are missing with current tools: organized message boards, workflow and resource management and the most important for me, coding architecture abstraction. There are tools that make that it very easy to build that kind of community platform and I'm trying to work things out with a CMS. It won't be long and we are already talking about the first steps of our work so it should start quite soon. > Don't get me wrong, your enthusiasm is very welcome, but I think the > tools available now (html editing, Forrest for previews, svn + lists + > wiki for collaboration) are good enough to do useful work. But if the > community does not have enough "collective energy" to do the work, > nothing happens. I totally agree with your concept of "collective energy", but when collective energy dissipates in technical details frictions, it often remains quite low compared to what it could be if things were... easier. > Let's get something done with the tools in place today before declaring > them inadequate - the improved infrastructure created by Reinhard, > Upayavira and others is just starting to bear fruit, building on this > makes a lot of sense, but *content* needs to be created. I insist on that once again. I don't consider current tools as inadequate, they are essential but using them directly leads to some very annoying things such as those we can read on the wiki for example : non-terminated tutorials, no table of content, no common styling or structure, no versioning of documents or lifecycle management. It's better than nothing but once again, for the kind of complete tutorial we plan to write, it doesn't fit. So we will totally integrate with common tools, but for now we plan to use an intermediary platform to analyze and build the content, to get it to a nearly-finished state before writing things on the wiki or making a request in bugzilla. That's the general idea... When you want to go from one side of the river to the other side, you can dive and swim, or you can quickly build a pirogue that will be more efficient, that will be able to carry many more people and scare far less.... -- Sebastien ARBOGAST
