This site has been archived and you can no longer log in or post new messages. For up-to-date community resources please visit ezplatform.com

eZ Community » Forums » Discussions » eZ Publish documentation - what next?
expandshrink

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

» Read full blog post

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.

Wednesday 20 April 2011 12:44:25 pm

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.

Sunday 24 April 2011 8:11:08 pm

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.

Modified on Sunday 24 April 2011 8:14:48 pm by Luc Chase

Tuesday 26 April 2011 1:35:23 pm

My own wishes:

1. reopen commenting asap blunk.gif Emoticon

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)

Wednesday 27 April 2011 1:21:04 am

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.

Thursday 28 April 2011 12:04:24 am

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. happy.gif Emoticon

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 happy.gif Emoticon

Erland Flaten

Monday 09 May 2011 11: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/Upgra...pgrading-to-4.5-from-4.1-4.2-and-4.3

Geir Arne Waaler

eZ Documentation

Monday 09 May 2011 11: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

Modified on Monday 09 May 2011 12:29:40 pm by Nicolas Pastorino

Monday 09 May 2011 11:42:52 am

http://doc.ez.no/eZ-Publish/Upgra...pgrading-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 happy.gif Emoticon

Monday 09 May 2011 12:55:23 pm

My wishes for the documentation are:

  1. More examples, i.e. for every parameter there should be an example
  2. Definitions of the valid range of parameter values (that's true for functions, operators, configurations etc.)
  3. 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)
  4. Detailed descriptions on frequently needed standard configurations - including an explanation why it should be done that way

Thanks a lot, keep going!

JT

Tuesday 17 May 2011 11: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. 

Modified on Tuesday 17 May 2011 9:06:36 pm by Luc Chase

Friday 16 September 2011 4:15:33 am

The reply has been removed because of violation of forum rules.

Wednesday 11 January 2012 1:46:31 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/Upgra...pgrading-to-4.5-from-4.1-4.2-and-4.3

Geir Arne Waaler

eZ Documentation

The above page, which leads to this page: http://doc.ez.no/eZ-Publish/Upgrading/Direct-upgrading/Direct-upgrading-to-4.5-from-4.1-4.2-and-4.3/Direct-upgrading-from-4.1-to-4.5

has a dead link for the "ezpublish requirements"

-------------------------------------------------------------

Check for requirements

The eZ Components and PHP requirements

The minimum version required of eZ Components with eZ Publish 4.5 is "ezcomponents-ezp45", containing a fix to the package. This version is bundled in eZ Publish 4.5 Enterprise. eZ Publish 4.5 is compatible with PHP version 5.2.1 and above, but certified on RHEL 6 and Debian 6, PHP 5.3.x distros. See http://ez.no/ezpublish/requirements for more info.

Can you point me in the appropriate direction as I want to upgrade from 4.1 to 4.6 if that is possible?

Modified on Wednesday 11 January 2012 1:47:27 am by cousin mosquito

expandshrink

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

36 542 Users on board!

Forums menu

Proudly Developed with from