A programmer's tale

eZ publish community documentation

July 20th, 2006

On ez.no I recently announced a documentation site based on eZ publish 3.8. It’s just one of the solutions that can be used to write additional documentation for eZ publish and for free community extensions. In this article I will explain the basic approach of this solution.

Goals

• replacement of README files: plain text documentation files are hard to read and navigate through
• uniformity: currently the documentation of most extensions is written add hoc and does not comply to any predefined structure
• interlink eZ publish documentation and extensions: when an extension offers an alternative to existing funtionality or complementary features, it should be linked to on the appropriate places in the eZ publish documentation
• multilingual
• discussion
• traceability

Technical implementation

The documentation site uses the general approach of a wiki, with single pages (of the content class Wiki page) linked to each other without a real tree structure. Instead of Wikitext markup, I’ve chosen to use an eZ publish ezxml attribute together with a WYSIWYG editor (SJSD or the eZ publish Online Editor). An attribute with the changelog datatype will be used to add changelog notes to a wiki page.

Each page belongs to a namespace (of the content class Wiki namespace). The content root node will act as the main namespace. Other namespaces are placed directly beneath the content root node.

When a wiki page is published for the first time, a workflow event (SCK-CEN create copy) will create a dedicated discussion forum for it.

For each language there will be a different URL based site access, e.g. http://pubsvn.ez.no/wiki/en for English and http://pubsvn.ez.no/wiki/fr for French. On each wiki page there will be a toolbox with a list of links to the same page in other languages.

The diffing functionality introduced in eZ publish 3.8 will be used to track changes between versions.

Layout

The site’s layout is loosely based on MediaWiki. On top you will find a small bar with account-related links (login/logout, notification settings, etc.). The main content is on the right side. On the left side there’s a logo, context-related toolboxes and toolboxes with other general functions (like search) or information (like the current visitor count).

What’s next?

Before we proceed with this project, we’d like to know who would like to join:

• further developement of the documentation site
• defining uniform structures for the documentation of extensions and eZ publish components (modules, template operators, template functions, etc.)
• using this solution for writing documentation for extensions

If there are enough people who want to get involved, we can start with:

• documenting the documentation solution itself (installation, how to use it, …)
• this will help us to find inconsistencies and must-have features that are still missing

Contact

Send an e-mail to kristof [dot] coomans [at] telenet [dot] be, with the subject “eZ publish community documentation”.

Entry Filed under: eZ Publish