Question th the eZ publish crew

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

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