Monthly Archives: September 2007

Without power, but still connected

Today the last bits of energy left my notebook as exess power. Now the whole thing turned into a rather expensive desktop statue.

But I m still here and still connected. The worlds best MP3-player saved the day. Thanks, PSP/2!

I can read, I can write (slowly, as this thing has no keyboard), I can access the net. I am alive!

OO-Con: Cultural Colonization

The first day has gone by, and a rather productive day it was.

The CEO of Redflag Linux held a keynote that was quite interesting and contained a couple of great points to think of: Why do we western software producers think that just slapping a translation on top of a product makes it perfectly suitable for the whole world?

In China they have a different culture with fundamental different approaches on how to solve problems and how to work with tools and each other. But corporations like Microsoft (he used that example, as he was speaking of the Office market, but later widened the blame to all kinds of software) simply ignore the traditions that exist everywhere and force users (by their sheer market power) to accept the western way of life. He specifically used the example of text-layouting, text processing and text-display to shed some light on how our system differs from theirs. Although most of his points sounded simple and easy to ignore, the sum of all of them forms a huge mass of annoyance.

And I think our tools are following the same trail. For the reporting engine I know that we do not support anything else than the Latin writing system (if other systems work, then this is just by accident). But for anything more arcane than the obvious, we cant even tell whether there would be an issue – as we simply dont know and never cared to ask.

Heck, we should go for it. BO, Cognos and Co are ignoring a huge market (not just China, but also India,whole Asia, the Arabic states, in fact: Everything except Europe and Northern America).

OK, they are not rich (yet), but a Penny is a Penny no matter whether you collected it from a poor or a rich men. But as there are more poor than rich people, collecting Pennies from them should give a better harvest ;). Or as the Redflag CEO put it: In China there a arbout 1.2 billion people without computer knowledge now. But they will catch up, and the decision of whether they get colonized by wester products or use own local products is made today.

We as Pentaho can help them to make the right decision, against the classical vendors to a great OpenSource product that does not limit their freedoms. But for that, we have to activate the potential in our local partners, who know their local cultures and encourage them to create not just translations, but a product that reflects the local culture of their own people.

P.S: While speaking about local culture. I’m down here without a working power supply – the cable is gone and after a whole day of desperate search, I’m convinced that there is not a single shop that sells a plain cable. So I’m running out of power – there is now 2 hours left in the battery and hopefully I will have enough electricity left tomorrow to return here (and to read mails. Argh, being offline makes me feel so 20th century).

Comparing Barcelona with Orlando

Same:

- The airport area looks the same. (Airports itself probably always look the same everywhere). The same mix of swamps, large free area that eventually turns into storage buildings or other low-density industrial area in a couple of years. The same large ads.
- Traffic jams. What use is a highway system, if everyone (except the motorcycles) is crawling?
- Climate. well, not the exactly the same. Barcelona is located directly at the sea, so its not *that* humid as Orlando.
- Air conditioning. Everywhere. And even large buildings dont have central ones, every window has its own small air conditioner attached.
- Food*. Not sure how Columbus made it to America with such food*. Well, I’m not sure how the americans survive with their food* either.
- Being offended by naked skin. You cant enter the Cathedral of Barcelona if you are a scrupelous woman that walks freely around with naked shoulders. Terrible such behaviour, isn’t it? And next woman want to vote. Seriously, even in Bavaria (which is strict** in religious topics) one would not be able to survive (policitally, not physically) with such an idea (ban naked skin, not voting***).
- The Sun is the same. I made some scientific experiments and can confirm: It produces the same kind of sun burn in both cities.

Different:

- Its older. The whole inner city of Barcelona smells of history.
- Its slower (especially in the rush hour). They take their time to build proper things. One cathedral is being built since 1882. They may finish it in 2020. Or later.
- Its has a city center. Orlando is a large assortation of villages, the city center is so small that you could miss it when you walk through it (I missed it twice. I was surprised once I found it. Now I dont miss it anymore.)

Tomorrow the OpenOffice Conference will start in the old university. The building itself feels more like a museum – old paintings and beautiful gardens. Being there makes you feel as if you traveled back in time 600 years (except for the existence of ring-tones and the non-existence of the spanish inquisition).

* The term food is used loosely here. In some countries chefs may be burned (or worse: fed such things) for comming up with such creations. But visiting either city is always a good time to loose some extra pounds of body weight.

** Strict, in comparison to the other German states. Not as strict as Vatican city, of course.

*** In Bavaria, there is no sense in inventing voting. There is just one party that counts, so it more or less comes down to a Yes or No thing. And Nos dont count either.

Doing Java-Doc is more than just slapping comments on the code

Whenever a project reaches the point where we may be tempted to call it a stable version, we enter the stage of updating the source code documentation. Our engine has been known for its comprehensive JavaDoc documentation in the past (yeah, the user documentation is a whole diffent chapter). Even OHLOH noticed that we have a good share of documentation.

But how do you recognize good documentation? First, it must be complete, of course. Second, it must be comprehensible. And third: It must be useful to the reader. That really doesn’t sound complicated, doesn’t it? But then again: The documentation of most projects (including my projects from time to time) just sucks. So maybe it is not that easy as it sounds.

Providing complete documentation is not just a matter of slapping comments to each and every method and class. Completeness also means, that it covers all the pitfalls and allows the reader to understand how things are supposed to work. A complete documentation should give enough information to allow the reader to reimplement everything from scratch. In my book, the documentation of the JDK itself is a great example what completeness could mean.

Writing comprehensible documentation requires to cover two aspects. First, the documentation should be readable. Grammar and orthography should march the basic level of the language. Errors can always happen – in code and in the documentation. But if the text is so full of errors that a common reader can no longer guess what the text meant, then it might be better to have no documentation at all. I know, for non-native speakers, this can be a challenge at first, but given our modern times, it is not hard to let a native speaker proof-read the texts. The documentation should contain complete sentences and should not try to be cryptic (in the sense of letting a hard-core mathematican explain hard-core mathematics to the unexpecting first-grade students). The documentation should either explain concepts that may be unfamiliar to the target audience or should contain links to further readings that explains these new concepts. Especially when the code uses or implements a certain standard, actually referencing that standard can greatly clear things up. As a positive side-effect, the documentation can skip all those parts that have been covered in the standard already. (Isn’t that the best reason to embrace standards in the first place?)

And last but not least: Being useful! We all learned in school, that each text should be written with a certain target audience in mind. The source-code documentation, like any other text, therefore should be written for the assumed user of our code.

If we look at our classic-engine, we have two classes of recipients, The frontend part of the code, the part that is used to define reports and to start the report processing is mainly used by users of the library. Users (for our purposes here) want to utilize the engine to generate reports, but they do not expand the functionality of the engine itself. Once a developer starts to hunt bugs or adds or changes functionality of the engine, the ‘user’ turns into an ‘implementor’.

Both groups have fundamental different needs. New users tend to be unfamiliar with the reporting terms we use. They do not know the concepts we use, and to be honest, unless they see how these things help them to get their job done faster they couldn’t care less about these concepts. For these users, our documentation should be shift and should introduce the basic concepts gently. Implementers, on the other hand, need (or even want) all the dirty details. They should be familiar with the basics already and are (so I hope) not scared to dig into details of the technologies and standards involved.

For us this means that we have to solve to conflicting aims. We must provide easy access without flooding the users with technical terms (and therefore scaring them away) while providing enough details to the implementors, so that they can get their job done without unnecessary code crawling. How we solve that? Front-end classes get documented for users, and all the backend classes get geeky developer documentation. The engine already shields the users from the backend classes – there is no direct way to invoke them from outside the report process and there should be no access path left that would let a user get through to that code.

As we expect that implementers are able to read code, the backend documentation will be an agumentation to the source-code. It therefore (contrary to all theories of sourcecode documentation) does not document the contract, but explains how and why we did what the code says there. The engine’s backend does not form an interface that we expect to be implemented by some independent vendor. There’s just the code that does the work – and documentation that explains how the code is supposed to do the work.