eZ Publish documentation - what next?

Wednesday 20 April 2011 1:49:22 am - 10 replies

Introduction

The eZ Publish documentation has always been a shared effort with many different contributors putting word on word, code snippet on code snippet. Slowly it has evolved into what it is today, an information highway. The standards and quality of this highway can and should be discussed, and it can surely only be evaluated by its users.

» Read full blog post

10 replies

Author	Message
paul bolger	Wednesday 20 April 2011 3:44:25 am Regarding the closing of comments on the docs - why not just turn off html in those comments and in the user signatures? Most of the spam seemed to be people who wanted to get a link to their lamearse website published. Wouldn't stopping that stop the spam? I used to find the ability to add a comment which detailed something I had worked out really useful, both as a note to myself and as a way of finding out what others thought of what I wrote. Paul Bolger
Luc Chase	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
Gaetano Giunta	Tuesday 26 April 2011 4:35:23 am My own wishes: 1. reopen commenting asap ;-) 2. a "recipes" section, dedicated to 'advanced' topics (ie extensions), where each recipe/blueprint is the description of how to solve a specific problem. Recipes should be short, ranging from the full tutorial to the single FAQ/answer, and organized by topic (also massively linked to existing material on the web, on share.ez.no etc) Principal Consultant International Business Member of the Community Project Board
cousin mosquito	Tuesday 26 April 2011 4:21:04 pm An FAQ is a great place to start. Let me know when you want to know what to put in it. You need to encourage people to want to use EZ, even if they are not expert coders. Asking the dumb questions for your benefit
Erland Flaten	Wednesday 27 April 2011 3:04:24 pm All I can say now is that the documentation is bad on the beginners level. Its difficult to understand the basics and how set up and configure a site. As I remember the language are too abstract and technical. Technical is ok, but must be explained. Its very good that EZ puts some effort on making the documentation better. :) I am a "casual user" of EZ and know html/css pretty well, javascript not so good and php worse. EZ Doc is written by and targeted to poeple who know PHP and unix stuff. In some days i plan to update a site which use EZ, cant see I am looking forward to do that update. Very complicated to do upgrades of EZ. Thats why I have been waiting. Hope to write down some spesific probs when I do the update. THanks, and good luck with the doc works :) Erland Flaten Erland Flaten Lilllehammer, Norway
Geir Arne Waaler	Monday 09 May 2011 2:23:58 am Some comments to people's comments! Thank you.. and keep them coming! A comment to Erland Flaten: Hope you find this useful: We have a new "Upgrade kit", trying to do something difficult a bit simpler. http://doc.ez.no/eZ-Publish/Upgrading/Direct-upgrading-to-4.5-from-4.1-4.2-and-4.3 Geir Arne Waaler eZ Documentation
Geir Arne Waaler Moderated by: Nicolas Pastorino	Monday 09 May 2011 2:29:17 am As regards to the FAQ. I have started work on that, and even though it is early days, I have published it. Will create proper ways of accessing it. For now, those of you with a special interest may look no further, only click this link to the FAQ. Please keep feedback coming. If you have a particularly useful question, I will update the FAQ immediately! Geir Arne Waaler eZ Documentation
Erland Flaten	Monday 09 May 2011 2:42:52 am " http://doc.ez.no/eZ-Publish/Upgrading/Direct-upgrading-to-4.5-from-4.1-4.2-and-4.3 " I was just started looking into upgrading my site and this will for shure be usefull.Thanks :) Erland Flaten Lilllehammer, Norway
JT -	Monday 09 May 2011 3:55:23 am My wishes for the documentation are: More examples, i.e. for every parameter there should be an example Definitions of the valid range of parameter values (that's true for functions, operators, configurations etc.) Commenting should be possible - compare it to php.net: comments are very important for shotcomings of the "manufacturers" documentation, often the user comments are more helpful than the documentation of zend (and they add value by clearifying examples) Detailed descriptions on frequently needed standard configurations - including an explanation why it should be done that way Thanks a lot, keep going! JT
Luc Chase	Tuesday 17 May 2011 2:13:56 am The style of documentation at YiiFramework is quite a good example for beginners. http://www.yiiframework.com/screencasts/ And http://codeigniter.com/user_guide/ is another. The Web Application Service Provider

You must be logged in to post messages in this topic!