Community documentation etiquette

Monday 08 September 2003 12:09:39 am

I recently added a document to the system that lists template variables and what they are. It was intended to be a reference so that I wouldn't have to keep added {$module.result|attribute(show,3)} to my template code. I thought I'd add the document to the community list so It could help others.

Since then a couple of things have happened:

1. The document structure has been changed. Not a really biggie but I preferred my formating ;) Is there a "style guide" for documents? The formating changes seems to be at the whim of the next person that edits the document. (I can't go back and edit it now that someone else has edited the file)

2. Additional information has been added to the document. Great! except the additional information, while it tries to do a similar job, doesn't follow the conventions in the original document, is incomplete and has a completely different style to the original.

It would make sense for the additional information to have been made a subdocument.

It concerns me that there seems to be little etiquette when it comes to the community documentation. After this experience I'm reluctant to contribute additional documentation.

Why do I no longer have any editing right over this page?

Cheers
Bruce

My Blog: http://www.stuffandcontent.com/
Follow me on twitter: http://twitter.com/brucemorrison
Consolidated eZ Publish Feed : http://friendfeed.com/rooms/ez-publish

Monday 08 September 2003 8:34:57 am

Hi Bruce,

Its me who upset you, and I did not intend to do that, sorry.

>1. The document structure has been changed. Not a
>really biggie but I preferred my formating Is there a
>"style guide" for documents? The formating changes
>seems to be at the whim of the next person that
>edits the document. (I can't go back and edit it now
>that someone else has edited the file)

Well, that's the point of the wiki style documentaton. For this particular page, I noticed the confusion of which variable is available where. There is a substantial difference on what is available where and this does not only depend on caching. I tried to clarify this for the pagelayout and view templates.

>2. Additional information has been added to the
>document. Great! except the additional information,
>while it tries to do a similar job, doesn't follow the
>conventions in the original document, is incomplete
>and has a completely different style to the original.

Sure, its incomplete, I searched for this in the index.php and kernel functions but did not look at everything (yet). I thought it did make sense to change the style to reflect the changed content.

>It would make sense for the additional information
>to have been made a subdocument.

For the content yes, its too long now. It should better be split up between the various "types" of templates.

>It concerns me that there seems to be little
>etiquette when it comes to the community
>documentation. After this experience I'm reluctant >to contribute additional documentation.

Quite some pages I wrote before are edited too, but that's the purpose of the wiki style documentation project. The ez crew is currently restructuring/editing the docs (which is needed), so expect more changes.

>Why do I no longer have any editing right over this
>page?

If you cannot edit the page anymore, than that's a bug, but I don't think you mean that. For other editing rights, please review the introduction page: its a GPL-ed wiki style project.

-paul

eZ Publish, eZ Find, Solr expert consulting and training
http://twitter.com/paulborgermans