Question th the eZ publish crew

Share » Forums » General » Question th the eZ publish crew

Sunday 04 July 2004 5:35:41 am - 3 replies

3 replies

Author	Message
Balazs Halasy	Tuesday 06 July 2004 1:17:20 am Hi, The eZ publish documentation will hopefully be improved within the current (or the next) development cycle. It is on the drawing board, but we haven't decided exactly what and how it will be done. I hope the community understands that it takes a lot of time and effort to write good and consistent docs. My question to you would be: What do you mean by "complete reference book with full documentation" - could you please shed some light on what you're missing at this point? I don't know if you have seen this or not, but there is actually a pretty comprehensive reference chapter within the current version of the docs: http://ez.no/ez_publish/documentation/toc/(from)/44024 ...which covers all the template functions, all template operators, different data fetching techniques, modules and XML tags. Balazs
Stuart DH	Wednesday 07 July 2004 3:07:13 am I've also got the book and I think I understand what you mean. It's not very fluid, makes quite a few assumptions about the user's knowledge of CMS and eZ Publish, and I don't think that it is really suited to newbs. The documentation section certainly feels more organised and structured, but it is in serious need of being updated/errors corrected etc. I've tried to make my way through it on about five different occasions but it is just littered with problems. Almost every page has many, many comments from confused and fustrated users and yet they seem to go unanswered for several months, with little feedback from eZ Systems. I've said it before and I'll say it again. I really don't think that eZ Publish is the big scary app that everyone makes it out to be. It is really just being let down by the many errors/ommissions in the documentation and the way that the tutorials are presented. I've offered to create video tutorials for eZ Publish but I've received very little support. It takes a relatively short amount of time to produce video tutorials (compared to HTML versions). They are a lot quicker for users to go through they clearly show every single step. I could probably record all of the TSCM tutorials to video within just a few days, but they are so full of problems that at the moment it simply isn't possible. So once again I will lay down the gauntlet. If someone at eZ systems will answer my problems with the tutorials with a fast response, I will be willing to record them to video. I will even let them have direct access to my webspace to see where things are going wrong. http://www.wildaboutbritain.co.uk
Dirk Billerbeck	Wednesday 07 July 2004 6:35:47 am Hello Balazs, as someone who has already written some technical documentations I know how hard it is to produce a well-written, consistent and complete documentation. But I have to second Rami and Stuart: Although the documentation is already much better than some months ago there is still a <b>lot</b> of work to do. The extent of information should be increased and the representation should be improved. Right now the learning curve is still very steep. IMO each reference entry should follow the same structure: 1. Name of the function/operator/etc. 2. Short general description 3. Where can it be used? 4. Who can use it? 5. Syntax diagram (parameter order, required/optional parameters, <b>all possible</b> parameter values, parameter dependencies, etc.) 6. Detailed description of each parameter 7. (Useful) examples 8. Related commands/functions/operators/etc. For a (IMO) well done technical reference have a look at http://publib.boulder.ibm.com/infocenter/tivihelp/topic/com.ibm.itsmcw.doc/anrwrf52255.htm But beside the structure of the documentation eZ systems should create a organizational process to make sure that the documentation is kept up to date or gets corrected. When implementing a new feature or changing the way something works the documentation should be updated simultaneously. And according to my experience this is much easier when starting with it as soon as possible in the development cycle. Hopefully the eZ publish documentation will evolve the same way the eZ publish CMS has done. Regards, Dirk

Author

Message

Balazs Halasy

Tuesday 06 July 2004 1:17:20 am

Hi,

The eZ publish documentation will hopefully be improved within the current (or the next) development cycle. It is on the drawing board, but we haven't decided exactly what and how it will be done. I hope the community understands that it takes a lot of time and effort to write good and consistent docs. My question to you would be: What do you mean by "complete reference book with full documentation" - could you please shed some light on what you're missing at this point? I don't know if you have seen this or not, but there is actually a pretty comprehensive reference chapter within the current version of the docs:

http://ez.no/ez_publish/documentation/toc/(from)/44024

...which covers all the template functions, all template operators, different data fetching techniques, modules and XML tags.

Balazs

Stuart DH

Wednesday 07 July 2004 3:07:13 am

I've also got the book and I think I understand what you mean. It's not very fluid, makes quite a few assumptions about the user's knowledge of CMS and eZ Publish, and I don't think that it is really suited to newbs.

The documentation section certainly feels more organised and structured, but it is in serious need of being updated/errors corrected etc. I've tried to make my way through it on about five different occasions but it is just littered with problems. Almost every page has many, many comments from confused and fustrated users and yet they seem to go unanswered for several months, with little feedback from eZ Systems.

I've said it before and I'll say it again. I really don't think that eZ Publish is the big scary app that everyone makes it out to be. It is really just being let down by the many errors/ommissions in the documentation and the way that the tutorials are presented.

I've offered to create video tutorials for eZ Publish but I've received very little support. It takes a relatively short amount of time to produce video tutorials (compared to HTML versions). They are a lot quicker for users to go through they clearly show every single step.

I could probably record all of the TSCM tutorials to video within just a few days, but they are so full of problems that at the moment it simply isn't possible.

So once again I will lay down the gauntlet. If someone at eZ systems will answer my problems with the tutorials with a fast response, I will be willing to record them to video. I will even let them have direct access to my webspace to see where things are going wrong.

http://www.wildaboutbritain.co.uk

Dirk Billerbeck

Wednesday 07 July 2004 6:35:47 am

Hello Balazs,

as someone who has already written some technical documentations I know how hard it is to produce a well-written, consistent and complete documentation.

But I have to second Rami and Stuart: Although the documentation is already much better than some months ago there is still a <b>lot</b> of work to do. The extent of information should be increased and the representation should be improved. Right now the learning curve is still very steep.

IMO each reference entry should follow the same structure:

1. Name of the function/operator/etc.
2. Short general description
3. Where can it be used?
4. Who can use it?
5. Syntax diagram (parameter order, required/optional parameters, <b>all possible</b> parameter values, parameter dependencies, etc.)
6. Detailed description of each parameter
7. (Useful) examples
8. Related commands/functions/operators/etc.

For a (IMO) well done technical reference have a look at
http://publib.boulder.ibm.com/infocenter/tivihelp/topic/com.ibm.itsmcw.doc/anrwrf52255.htm

But beside the structure of the documentation eZ systems should create a organizational process to make sure that the documentation is kept up to date or gets corrected. When implementing a new feature or changing the way something works the documentation should be updated simultaneously. And according to my experience this is much easier when starting with it as soon as possible in the development cycle.

Hopefully the eZ publish documentation will evolve the same way the eZ publish CMS has done.

Regards,

Dirk

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

design implementation by Netgen / design by Xvision

Question th the eZ publish crew

Question th the eZ publish crew

Forums menu