Product   Documentation        
          Read all about it!  






Pentaho’s documentation is substantially worse than that offered by Oracle: it varies between the good, the bad, and the AWOL! Indeed, if you’re tasked with doing a quick analysis of BI suites with a view to coming up with a short-list for a more detailed evaluation, then it’s quite possible you’ll exclude Pentaho on the grounds that you couldn’t quickly find the information you needed to confirm that, at least in principle, the product might be fit for purpose.


For an organisation like Oracle with substantial licence revenues, it’s possible to offset the cost of servicing confused users who are seeking support because the product documentation is unclear. However, the clear objective for any subscription-based, open-source vendor is to avoid support calls if at all possible: an excellent set of product documentation and accompanying tutorials is key to maximizing revenues – which makes the variable quality of Pentaho’s documentation all the more puzzling.


Pentaho’s documentation reflects its community-based origins, being variable with regard to both its quality and quantity, with a focus on developers who already understand the product, rather than on those who are learning to use the product for the first time.


The introduction of a more comprehensive, well organised, and carefully reviewed set of documentation is required, one that meets the expectations of the enterprise: the documentation needs to offer a broad overview of each area of functionality, and needs to guide developers unfamiliar with the product through a set of carefully worked examples.



Documentation Issues


As to the specifics of what’s wrong with the Pentaho documentation, here are some examples:


*  While the product is very well implemented and generally intuitive to use, on-screen help buttons are often absent.


*  There is a dearth of diagrams that would allow potential clients to quickly gain an understanding of the product architecture and functionality.


*  There is very little by way of high-level explanatory material that would give an overview of a specific area of functionality – the evaluator is often forced to read through low-level implementation details, and then extrapolate.


*  While some functionality is accompanied by a detailed explanation, elsewhere explanations are often far too terse to be useful; and worked examples are often few and far between.


*  While some tutorials are excellent, others are bug ridden.


*  Pentaho has documentation for various releases of both the subscription-based and the community-based versions of the product. A Google searches on a particular topic may turn up information from any version of either type, and it is not always clear which is which; for example, an evaluator searching for “installation requirements” or “system requirements” will currently end up on a page that does not indicate the version and which displays out-of-date information.


*  Pentaho’s documentation is getting worse, not better. The old information site has an excellent split-screen design, with a hierarchy of folders displayed in the left-hand panel (think Windows Explorer); navigating the hierarchy allows the user to quickly determine what documentation topics are available and how they are nested, with the contents of the context topic being displayed in the panel to the right. However, the current information site requires the user to drill-down from linked-page to linked-page, so that the overall structure of the documentation is unclear. It’s often easier to start with the old information site to get an overview, and then use the current site to see if the documentation has changed in subsequent releases.


*  The search facility within the current documentation site will not always find the relevant topic, particularly when searching for detailed information, such as specific ETL steps – a Google search is far better but will, unfortunately, turn up information applicable to all versions and types.


*  The subscription-base documentation is incomplete. After drilling-down on the subscription-based web pages, it’s common to be transferred to community-based documentation, which can be edited by any member of the Pentaho community – while there is a lot to be said for this “Wikipedia” approach to documentation, it does not guarantee that the information provided is either correct or comprehensive.


*  A topic may have little by way of useful documentation in the current subscription-based version, but may have much more useful documentation in an earlier, community-based version, so the user is forced to search all available documentation, and then make an educated guess as to whether the information gleaned is relevant to the current subscription-based version.


*  There is as yet no PDF documentation for the latest Pentaho release.