Improvement of the Technical Manual's Reference part

Next topic

Author	Message
Jozef Baum	Friday 31 July 2009 11:42:50 am I would like to suggest a serious review of the Technical Manual's Reference part. For instance, let us go to the chapter about the configuration files, and look at the settings for site.ini, a very important configuration file. There are very much settings for this file in the default site.ini file which are not documented in the Reference. Also, there are settings about which the Reference is incorrect. Just 2 examples: - DatabaseImplementation "Usage: DatabaseImplementation=ezmysql\|ezpostgresql\|ezoracle" ezmysqli is missing, although Andreas wrote a comment about this. - GeneratePasswordIfEmpty "If GeneratePasswordIfEmpty is set to false the user must select a password that is at least three characters long." This is incorrect. The minimum password length has no fixed value of 3 characters. This is just the default value in site.ini. But it can be set to another value with MinPasswordLength.
Heath	Monday 17 August 2009 8:57:53 am I tend to agree with this request in general. This part of the manual has always been an eyesore. It would be very fine indeed if this was ever addressed. I know I always end up landing on one of these pages only to find no useful information or content displayed. Cheers, Heath Brookins Consulting \| http://brookinsconsulting.com/ Certified \| http://auth.ez.no/certification/verify/380350 Solutions \| http://projects.ez.no/users/community/brookins_consulting eZpedia community documentation project \| http://ezpedia.org
Jozef Baum	Wednesday 19 August 2009 5:14:42 pm Thank you for your posting, Heath. Instead of loosing lots of time to try to find out how eZ Publish works, I am waiting for the book "eZ Publish 4: Enterprise Web Sites Step-by-Step", which should be available in October. However, it will comprise only about 300 pages. Therefore, it cannot be a substitute for the poorly written and very incomplete technical manual with its 1880 pages in its A4-PDF edition. So, although the eZ Systems crew clearly seems to largely underestimate the enormous drawback the lack of good documentation constitutes for eZ Systems to be used by more people, I feel we cannot insist enough by asking them to eventually improve the documentation to the quality level of eZ Publish. Of course, the lack of good documentation will push some users to pay for training. But a lot of other users will simply turn to a perhaps less powerfull, but well documented system. Look at other software with a licence model similar to that of eZ Publish (commercial and open source). OpenSolaris is very well documented by Sun Microsystems. OpenSuse Linux is very well documented by Novell.

Author

Message

Friday 31 July 2009 11:42:50 am

I would like to suggest a serious review of the Technical Manual's Reference part.

For instance, let us go to the chapter about the configuration files, and look at the settings for site.ini, a very important configuration file.

There are very much settings for this file in the default site.ini file which are not documented in the Reference.

Also, there are settings about which the Reference is incorrect.

Just 2 examples:

- DatabaseImplementation

"Usage: DatabaseImplementation=ezmysql|ezpostgresql|ezoracle"

ezmysqli is missing, although Andreas wrote a comment about this.

- GeneratePasswordIfEmpty

"If GeneratePasswordIfEmpty is set to false the user must select a password that is at least three characters long."

This is incorrect. The minimum password length has no fixed value of 3 characters.
This is just the default value in site.ini.
But it can be set to another value with MinPasswordLength.

Heath

Monday 17 August 2009 8:57:53 am

I tend to agree with this request in general. This part of the manual has always been an eyesore. It would be very fine indeed if this was ever addressed. I know I always end up landing on one of these pages only to find no useful information or content displayed.

Cheers,
Heath

Brookins Consulting | http://brookinsconsulting.com/
Certified | http://auth.ez.no/certification/verify/380350
Solutions | http://projects.ez.no/users/community/brookins_consulting
eZpedia community documentation project | http://ezpedia.org

Jozef Baum

Wednesday 19 August 2009 5:14:42 pm

Thank you for your posting, Heath.

Instead of loosing lots of time to try to find out how eZ Publish works, I am waiting for the book "eZ Publish 4: Enterprise Web Sites Step-by-Step", which should be available in October.

However, it will comprise only about 300 pages. Therefore, it cannot be a substitute for the poorly written and very incomplete technical manual with its 1880 pages in its A4-PDF edition.

So, although the eZ Systems crew clearly seems to largely underestimate the enormous drawback the lack of good documentation constitutes for eZ Systems to be used by more people, I feel we cannot insist enough by asking them to eventually improve the documentation to the quality level of eZ Publish.

Of course, the lack of good documentation will push some users to pay for training. But a lot of other users will simply turn to a perhaps less powerfull, but well documented system.

Look at other software with a licence model similar to that of eZ Publish (commercial and open source). OpenSolaris is very well documented by Sun Microsystems. OpenSuse Linux is very well documented by Novell.