Forums / Suggestions / Community documentation etiquette

Community documentation etiquette

Author Message

Bruce Morrison

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

Jan Borsodi

Monday 08 September 2003 2:44:45 am

We will create some guidelines for how documentation should be, we are currently working on restructuring the documentation (currently offline).
We will probably have a general guideline and specific guidelines for writing template functions/operators etc.

--
Amos

Documentation: http://ez.no/ez_publish/documentation
FAQ: http://ez.no/ez_publish/documentation/faq

Paul Borgermans

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

Bruce Morrison

Monday 08 September 2003 3:30:55 pm

Hi Paul

I would have taken this off line if I knew your email address. Thanks for answering.

I posted this message because there are no style guidelines and there needs to be. You changed the presentation and content style of the document as well as adding additional documentation.

I think the wiki type (and yes, I have read the documentation) of documentation system is great and encourages the community to share information. However I do believe that there is a level of etiquette required to make these systems work effectively.

Cheers
Bruce
brucem@designit.com.au

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