Skip to: content | sidebar | login

Home » Archive » 2008-12-01 - 2008-12-31

Home: Archive

2008-12-01 - 2008-12-31

Cumulative update

Posted on 12/01/08 13:07:44. | Bookmark this on Delicious

Yes. OK. I am not so good in blogging, always hesitating what deserves publishing... This time I post a sort of cumulative update as few things happened within last two months.

First, I finally completed ITIL Service Manager course and on 14-16.10.2008 took exams. That was a nightmare.

They sent us a case study. Something about a transportation company that was a joint of 3 national comapnies in 3 European countries. As they grew they decided to go ITIL. Upon the background EXIN prepared two set of 5 questions covering both Service Support and Service Delivery areas of ITIL.

The exam itself consists of two parts - one day each. Each part is a 4 hrs, hand written test that you have to give requested answers and no more. If you flow too far you won't get points. If you are not precise, you lose points. Ouch.

After exams were done, I was waiting daily for a postman to deliver me any news. Evetually, last week they called and announced that I passed!!! OMG, what a relief.

Next, in the begining of November, Piotras and I we went for Midgard Gathering to Helsinki. Thanks to out valuable Finish friends we had a great time hacking Midgard, learning about PHP unit tests (that was Sebastian Bergmann), discussing future development, compiling Midgard on bloody M$ platform (he he he) and of course beer, sauna and guitar wars.

We saw new Midgard talking to Jabber via D-Bus signals and sending IM notifies about changes, we saw Vala playing nice with Midgard, we also saw amazing USB finger-drive from Jerry :) And most of all we were wonderfully hosted by Satu and Oskari Kokko (many many hugs and thanks)

One of deliverable from the Gathering was that I was appointed as Documantation Manager for the project. That means I am to make all those naughty developer to keep their code documented so that Midgard finally provides a source of knowlege, also for dummies.

Last night I have refactored midcom.admin.help component to be more automatic and scan documentation from components folders. This way, overloaded coders only have to put some text files and MidCOM itself will create docs on-line.

Hmm... When I started this post I felt I had so many things to say, but somehow I forgot...

Towards better Midgard documentation

Posted on 12/02/08 11:39:01. | Bookmark this on Delicious

Last few days I've spent on extending midcom.admin.help plugin to make it better doc reader for end users. Let's recap what it can do now and how you, my fellow component developer, can improve your docs, and how you, my fellow user can benefit from it.

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:

net.nehmer.blog

News items and blog entries management. Provides a variety of display styles and RSS feeds.

 

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:

mgdschemas.jpg

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:

routes.jpg

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.

Back

Return to top