Documentation Work in Progress

Over the last few weeks I lived with a split personality. OK, those who know me probably say: So what’s new then?

The new thing is: There’s documentation brewing. In a parallel effort of cooking the bug-fixes for the 3.7.1 release and writing documentation, I am preparing the scene for a better product now. The Pentaho Report Designer is nice, and quite a improvement to the previous releases, but at the moment it is only ‘commercial grade’ software en par with all other reporting offerings out there. For me, ‘commercial grade’ is never a badge of honour, as it usually means bug-fixes come late (if ever) and shiny check-box-list features get more energy than they deserve.

So let’s turn the rudder, hang the petty officer and then raise the skull flag – we’re going on a tour!

I already took the liberty to clean out the Wiki. Instead of presenting a S**t-load of obsolete documentation, I made the front page nearly empty. There is only one choice to make: Either go to the User Guide for Report Designer or try to dig your way through the random collection of the developer documentation.

Personally, for the next months to come, I will concentrate solely on the user guide. Developers? They have the source code. And if you are not willing to read the source code, then fork off $35 to get Will Gorman’s book. And if you are not willing to spend that much, then try your luck with Crystal Reports. 😉

The installation documentation as well as the first walk-through is finished now. All other chapters will come over time – whenever my time permits to do a bit here. And once again: I will concentrate on the novice documentation before I dwell into the heavy stuff. If you’re smart enough to get a decent report running, you are very likely to ‘get’ the complex stuff at some point. If not, well, there’s always the forum, as before.

While writing the documentation, I do stumble across weird behaviour. Of course, where ever possible, I fix that rather than just document the weirdness. Our JIRA system now has a new ‘component’ called ‘usability’. This is my personal bucket for all bugs for which I think that they make it hard to use the report designer, and which are easy to fix at the same time.

How can you help?

First – report bugs. Every bug. Have you ever double clicked on a list hoping to select a element in a dialog? File a Improvement request. Have you felt annoyed by dialogs being to small by default? Jira it! Do you feel unhappy that you have to click three times instead of clicking just once? Or is there a message that you find just confusing? Tell us about it.

Have you written How-Tos for your users? Tell us about it! If possible, add them to the wiki. And even if you cant add them (as you are not allowed to publish company property, for instance) – tell us about it. If you had to spend time explaining it, chances are high that we can improve either the workflow to make it easier to use or we can provide similar documentation, so that everyone can profit from it.

This entry was posted in Development on by .

About Thomas

After working as all-hands guy and lead developer on Pentaho Reporting for over an decade, I have learned a thing or two about report generation, layouting and general BI practices. I have witnessed the remarkable growth of Pentaho Reporting from a small niche product to a enterprise class Business Intelligence product. This blog documents my own perspective on Pentaho Reporting's development process and our our steps towards upcoming releases.

1 thought on “Documentation Work in Progress

  1. Will Gorman

    Hi Thomas, I’m sure many in the community will thank you for your efforts! While writing the book, I had a very similar experience, it’s much easier to fix a usability bug sometimes then try to write a workaround in documentation! Keep up the great work!

Comments are closed.