How do I contribute to documentation?

Wednesday 05 April 2006 12:02:53 am

Good idea about SVN, kracker. Paulb and I are already doing this with our portals and it works very well.

Didn't had any time to improve my wiki further, but here's a screenshot of what I've made so far: http://blog.coomanskristof.be/wp-content/uploads/wiki_01.jpg . Don't expect too much of it because I'm not a webdesigner ;-)

At the top, you'll find some shortcuts to user info etc. At the left you have the logo and some context specific toolboxes (this article, search, in other languages, ... ). And at the right the content itself. Quite similar to MediaWiki. I'm not sure yet if it would be better to put those context specific toolboxes together with the real page content in module_result.content instead of the pagelayout.

Some stuff useful to have:

- changelog for wiki pages ( http://ez.no/community/forum/developer/object_edit_extension_handler_changelog , has not been tested with multilingual content yet )

- the xml block datatype relating objects (on attribute level) from links with the ezobject:// and eznode:// protocol ( http://ez.no/community/forum/suggestions/xml_block_links_and_related_objects ), or the wiki extension doing this (depends on which content format we will use)

- a "go" search button, similar to MediaWiki. I didn't look in the kernel yet to see how we can accomplish this. I think it's rather a "nice to have", not a "must have".

independent eZ Publish developer and service provider | http://blog.coomanskristof.be | http://ezpedia.org

Wednesday 05 April 2006 8:40:54 am

I am attending, even presenting :-))

We'll setup a prototype, at the latest by the end of april on pubsvn. The site design will be in svn too.

Q: should we create an alias like pubdoc.ez.no or is pubsvn.ez.no/docs or so OK?

And ultimately, since the machine behind pubsvn will be doing more things (like showcasing extensions where relevant), maybe pubsvn.ez.no should be renamed, like

community.ez.no

with

community.ez.no/svn the repositories
community.ez.no/docs documentation
community.ez.no/showcase extension demo's

The root and docs/showcase will be eZ publish powered then, with docs having a static cache.

Just a few thoughts

--paul

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

Monday 08 May 2006 10:08:41 am

I've been quite busy the last weeks, that's why I didn't get back to this thread earlier.

If there's still somebody interested I can make the wiki design available in it's current state (which is far from finished) from an SVN repository.

Before continuing I'd like to know in which direction you wish to go with the new projects section on ez.no (
http://ez.no/community/forum/general/new_project_section_on_ez_no ), in conjunction with the plans being made here.

Because it will also possible to write docs for extensions in the new projects section, I guess that will be the preferred place to have those docs, and not on a community documentation site?

And couldn't the eZ publish community documentation be a seperate project then in the new projects section? Will the provided functionality fit our needs to write and link docs?

I'm just thinking loud... What do you think?

independent eZ Publish developer and service provider | http://blog.coomanskristof.be | http://ezpedia.org

Tuesday 18 July 2006 9:15:07 am

Some time ago we (Paul and I) have set up a basic documentation infrastructure (wiki-like) at http://pubsvn.ez.no/wiki/

It still needs some (or maybe a lot of) template work, I didn't proceed yet because it is quite unsure if it is going to be used anyway if the new projects section has some place for docs too.

Don't take the current content in it too seriously, I just have been playing around :-)

I'll try to put online a document (request for comments) explaining the current approach of the tool.

independent eZ Publish developer and service provider | http://blog.coomanskristof.be | http://ezpedia.org

Friday 21 July 2006 11:03:14 pm

<b>Q:</b> <i>Where would you put make the base tools and (protecting user data) data available used in svn available to other developers? </i>

community.ez.no - the eZ community portal
doc.community.ez.no - the documentation
svn.community.ez.no - the repositories
showcase.community.ez.no - the showcase extension demo's

reducing url uri parameters from a base app url names (using dns) just seems cleaner, simpler than community.ez.no/showcase url style

<b>Q:</b> <i>@Kristof - If there's still somebody interested I can make the wiki design available in it's current state (which is far from finished) from an SVN repository.</i>

Yes, please make it available say on ez.no as a site design contribution (backlinked to svn release (anywhere)).

@Kristof - Thank you for posting a link to your example wiki setup.

<b>Q:</b> <i>@Sandro - Does it suffice to keep the discussion in this thread, or should there be a special forum on documentation or a mailinglist on ez.no?</i>

Yes! I think the length of this thread and others reflect the interest in documentors having their own set of forum an/or mailinglists on ez.no

<b>Q:</b> <i>@Sandro - * Infrastructure until eZ publish conference * It would be great to have the infrastructure ready for the eZ publish conference starting June 21, then we could all meet there and discuss further issues, especially questions of how the community doc content relates to the eZ systems doc content, as well as how community doc content is going to be maintained (structure, roles, etc.).</i>

What became of this discussion and project approach, etc details? What was the nature of the conversations?

<b>Q:</b> <i>@kracker - Questions about Infrastructure and Direction ... Where would you all start planning out the various aspects of code, content organization, implementation, roles, content review, etc on paper.</i>

1.0 - Who will speak up and add their name to the list of who is ready to commit to contributing feature implementation and integration.
1.1 - Who will be able to contribute x,y effort during the start up phase.
1.1.1 - Who will contribute system dev/maint effort during the start up phase.
1.1.2 - Who will contribute content dev/maint effort during the start up phase.
1.1.3 - Who will contribute organization dev/maint effort during the start up phase.
1.3 - Who will outline the (initial) layout of content
1.4 - Where is the list of system features sets are must have, nice to have, future improvement, if possible (looking to others for a prioritized todo list) to start with ...
1.4.1 - What's up with 'orphan pages' effort?
1.4.2 - Use of latest eZ oe for all content editing?
<i>http://ez.no/community/news/ez_publish_3_8_1_includes_gpl_online_editor</i>

<b>Q:</b> <i>@Kristof - Example Wiki Demo
> Some time ago we (Paul and I) have set up a basic documentation infrastructure (wiki-like) at
> http://pubsvn.ez.no/wiki/ - When can this be made available as a starting point for everyone via svn?</i>

<b>Q:</b> <i>@Sandro - Just do it!

> 1. Contributing to docs: Tell us your ideas how you would like to contribute.
> The community + eZ systems could plan and actually do the implementation together.
> Anyone in the community wants to take the lead here?</i>

This is still a good point, what topics do people what to see covered now that they find missing.

> 2. <i>Community docs: Set up a doc Wiki where the community creates, edits, structures, manages content.</i>

Ok ... so, we are only missing the part where registered/approved/blessed folks can at least start writing and publishing nods on the example wiki. Why not open up a copy of this to everyone to use ... (Re: http://pubsvn.ez.no/wiki or doc.community.ez.no )

<b>Q:</b> <i>What content hierarchy / structure has been outlined for the project (phase x, x months)</i>

<b>Q:</b> <i>What nodes/articles/pages need to be written (base + extensions + methods + practices)</i>

A: One of the larger list of content suggestion from Thomas at:
<i>http://ez.no/community/forum/general/how_do_i_contribute_to_documentation#msg93341</i>

<b>Q:</b> <i>Where is a new discussion / thread regarding the content that we want to create / populate the wiki</i>

<b>Q:</b> <i>What does eZ systems think of the idea to use community.ez.no alias(es) for the project / developers.</i>

<b>Q:</b> <i>How can users and developers request access to the wiki?</i>

<b>Q:</b> <i>How do user + wiki page (like file) permissions (read/write/edit/delete) work in this wiki? </i>

<b>Q:</b> <i>Can all (registered) users create new </i>

<b>Q:</b> <i>Request: RSS Feed for Recent Changes</i>

<b>Q:</b> <i>How can other users and developers to request access to integrate and extend the base set of tools / configuration used by the project to implement, test and make available to other developers.</i>

<b>Q:</b> <i>What language will the wiki be started with? English (en_US) or English (en_GB)?</i>

<b>Q:</b> <i>When will additional languages be supported on a per node basis, re: growing the non-english documentation contributions?</i>

<b>Q:</b> <i>What licence will the site aply to contributions from user?</i>

A: @kracker - I (still) vote for remaining consistent and keeping all the community documentation published to the site to follow the eZ systems docs and use the GFDL and allow the use of a specific CC license ( Attribution-ShareAlike 2.5, <i>http://creativecommons.org/licenses/by-sa/2.5/</i> ) in tutorials or articles as specifically requested by the author.

<b>Q:</b> <i>What are the project's names?</i>

A: Undetermined, eZ community documentation, eZ community documentation development, eZ publish templates documentation, eZ publish reference documentation, eZ publish documentation or even "Documentation" ... ?

<b>Q:</b> <i>Current Configuration Description link?</i>

A: eZ publish 3.8.X, extensions ( wiki(name), svn, etc ), design ( design(name) )

<b>Q:</b> <i>What is the current example doc/wiki link?</i>

A: <i>http://pubsvn.ez.no/wiki</i>

Update: <i>Sorry for the length, The summary / reply of the past 3 pages + FAQ Items got a little out of hand, I should be writing a tutorial on the wiki :D</i>

//kracker
<i>Blink 182 - So Sorry It's Over</i>

Member since: 2001.07.13 || http://ezpedia.se7enx.com/

Thursday 27 July 2006 4:45:53 am

Leif Arne, we have tried to do something about this topic.
Community for skandinavia is now online with free documentation and FAQ.

Available at: eznor.no

Check:
http://ez.no/community/forum/general/ez_publish_community_for_skandinavia_online_nor_swe_dk

Per-Espen

Wednesday 01 November 2006 9:33:17 pm

@David

> I read this thread with interest, as other open source projects
> have made excellent use of wikis to improve their documentation,
> and documentation is where I feel ezpublish needs the most work.

<b>Agreed.</b>

> I see the wiki has been up for a while,
> but this is the first time I have heard of it,

It's <i>true</i> the wiki is still in it's infant
stages and not well promoted (yet).

Something as simple as a <i>link</i>
on the pubsvn.ez.no index page would be nice start.

PubSVN: http://pubsvn.ez.no/
Community Documentation (Wiki): http://pubsvn.ez.no/wiki/

<snip />

> would submit that the ability to edit easily,
> for anyone in the community, is another
> part of a good wiki documentation project.

<b>Again, Agreed.</b>

I would like to see most of the public efforts
be coordinated to result in well organized
documentation as much as is possible.

> Having to request access means that many
> people will not contribute, where otherwise they might have.

Sadly I believe this is true as well.
I know I have personally requested access to the wiki,
to support the documentation of the commonly encountered
problem / solution I have encountered in the forums, irc, and in my own work.

I <i>eagerly await</i> return contact from the wiki admin
to see when I / Everyone will be able to contribute and how.

<i>//kracker
KMK - Why oh Why?</i>

Member since: 2001.07.13 || http://ezpedia.se7enx.com/

Sunday 05 November 2006 12:34:47 pm

The contents of that discussion can be found within the wiki itself
<i>http://pubsvn.ez.no/wiki/en/ez/pubsvn_meeting_minutes_2006_11_04</i>

I've added a number of example 'nodes' (as I am calling them)(right or wrong) <i>:)</i> into the community documentation as a starting point or subtle guide.
<i>http://pubsvn.ez.no/wiki/en/ez/documentation</i>

I've added a kind of project notes node
<i>http://pubsvn.ez.no/wiki/en/ez/pubsvn_project_wiki</i>

Take a look at the existing entries in the 'eZ' namespace (basically the wiki root)
<i>http://pubsvn.ez.no/wiki/en/ez</i>

//kracker
<i>kmk - we back ...</i>

Member since: 2001.07.13 || http://ezpedia.se7enx.com/

Monday 06 November 2006 12:54:25 pm

Hi all,

I think this is an excellent start! I noted there are plans to publicize in the forum, which I think is great, but I would also recommend that a link be put right on the front of ez.no if at all possible to draw the widest possible range of people (or possibly a link on the 'download ezpublish' page). I don't know if that's an option, but it would seem the most obvious place to draw people in.

David