|
Sunday 24 April 2011 11:11:08 am
Good to see some more attention in this direction. Documentation is typically a huge challenge for open-source projects, but strong documentation is extremely important to widespread adoption of OSS solutions. Seems much more difficult to do well than coding, and typically with less reward. I've always found the eZ user documentation to be quite good. But I would say that the lack of good, clear customisation or extension-building and developer documentation has been a serious impediment to widespread adoption of eZ Publish when compared with other widely used CMS systems. eZ Publish is a well designed, flexible system. But the EAV-based database schema alone is one that many would find a challenge. The override systems might at first seem over-done. The core is quite large, providing a large amount of out-of-the-box functionality, ready to use... if you can figure out how. The total number of books published on eZ is very small, and the number of in-depth, technical books published on eZ is tiny. A similar lack of documentation exists in the extensions directory. Many descriptions are too brief and do nothing to 'sell' the quality or purpose of the extension. eZ Components / Zeta Components documentation is relatively strong and a good example of how the rest of the system code should be documented. By now, (even though some is out-of-date and even incorrect) there's enough material in existence to form an adequate skeleton foundation, but it is not organised into any coherent paths for learning. So, perhaps the first thing to do is to define some learning paths and take an inventory of all the tutorial material available, plotting it all on those various learning paths. It would then also be easier to identify exactly what is still missing.
My feeling is that creating a good structure for the content, paths for using the material is the most important step. Not trying to first create top quality, up-to-date content or extra tools such as a Wiki. Don't try to be over-ambitious.
Make full use of what content is already there, but give it some order. A good IA exercise to make the material more accessible to the various types and competency levels of audience would go a long way. Once that basic structure is there, publish new content but have an approval workflow process in place for new or updated material to ensure all new content is reviewed for accuracy and marked as 'Reviewed'. Allow for private or public feedback on that content. Have a public system in place to accept requests for specific areas of documentation enhancement.
The Web Application Service Provider
|