The following write-up is related to latest Ragnaroek version and lives in SVN. Refer to http://trac.midgard-project.org/ to get help on syncing your repository with Midgard SVN.

For end users, editors and site developers it is crucial to know what they can do with given components and libraries. While midcom.admin.help lived there for a quite a time, it wasn't a good tool because it wasn't too handy.

First impression is the most important, therefore index page for help needs to be inviting. Now, it is sufficient to go to Online Help from your floating menu after you were logged in. A new popup windows will open presenting you current component's index page. Current means the one you were in when you hit 'help' button.

Index page shall contain a brief description about what given component does etc. For example:

Developers shall put index.lang.txt file into documentation folder.

Index page shall also contain a Table of Contents. TOC is generated automagically from all files matching name.lang.txt pattern in docs folder plus two special kewyords "MgdSchema classes" and "Routes" which are added to TOC if applicable.

"MgdSchema classes" will list all schemas introduced by a component. The list includes schema names and list of properties with descriptions for each schema.

Developers shall update schema definition files with special 'description' tag for each property:

<property name="topic">
        <description value="Parent midgard_topic ID" />
</property>

Schema list should look like this:

Routes is a artificial help item that shall display all URL routes handled by component. Each route shall provide handler name, controller class name, controller method and a brief description. Any route on the list shall be a link to MidCOM API doc stored at http://www.midgard-project.org/api-docs.

Developers shall add translation strings related to routes description to component's strings database using '{handler}_info' as string identifier. For example, in net.nehmer.blog, for 'ajax-latest' handler it would be 'ajax-latest_info' that would result in:

All remaining help files can have any names as long as they match the pattern name.lang.txt but developers shall remeber to put 'help_name' translation string into at least English component's translation database. To make it easier some common titles like 'help_style' or 'help_schemas' are stored centrally in midcom.admin.help's database.