Manual pages optimized for search as well as for reading

A lot of online manual pages today, especially Objective-C are written with full object description in the main body, which makes it very hard to read but very good for search engines. To mend things, we could implement a graceful degradation of certain terms into shorter versions, while using HTML5 abbr and CSS to hide or fade out the full description. We can even offer the option to apply such contractions or not, based on user preferences (some minds may be more comfortable reading the full description). All contractions could be programmatically formatted by the blog (app) engine, based on a key:value pair list of abbreviations and clarifications.

Here's an excerpt from such a man page taken from developer.apple.com:

Instance and Data Life-Cycles

It is important to understand that the life-cycle of the data a managed object represents is largely independent of the lifetime of individual managed object instances. In order to add a record to a persistent store, you must allocate and initialize a managed object—and then save the managed object context. When you remove a record from a persistent store, you should ensure its corresponding managed object is eventually deallocated. In between these events, however, you can create and destroy any number of instances of a managed object that represent the same record in a given persistent store.

And here's how it could look like when formatted for contractions:

Instance and Data Life-Cycles

It is important to understand that the life-cycle of the data a MO represents is largely independent of the lifetime of individual MO instances. In order to add a record to a store, you must allocate and initialize a MO—and then save the MOC. When you remove a record from a store, you should ensure its corresponding MO is eventually deallocated. In between these events, however, you can create and destroy any number of instances of a MO that represent the same record in a given store.

In the example above, we have abbreviations (MO and MOC) as well as clarifications (store = persistent store) which reduce the amount of text you need to read, nevertheless allows the user and the search engine to retrieve the expanded description. For the end user this optimizes the information intake, while the contractions work like instant definitions when clicked (touch interface) or rolled over with the mouse.

Of course, the whole jQuery processing of 

tooltip class

See the fileleader_tooltip.js javascript that makes this page work.

 would not be necessary if standard html tags would be fully implemented on mobile devices. Mobile web browsing seems to be going mainstream and the newly introduced HTML5 abbr tag is completely useless on both iPhone and Android platforms. And as much I understand the frustration caused by allowing tooltips all over the place, browsers should still provide the tooltips for standard html tags. Somewhat like on this page for example.