Eliminate the Middlemen

History…?

With the uprising of the world wide web, tech companies were forced to learn and experiment with publishing on the web. Of course, the marketing departments soon knew the paramount importance of a company web page – either you are on the www or you do not exist!

It took a little bit longer to publish products or services to the web. I still remember the time when company websites consisted of a single page with a phone number where to call for more information on our superb products and services.

While this has become a rarity, we are still in the stone age of the net when it comes to technical content. You often can download user manuals and product fliers as PDFs, yet some dinosaurs still give them to you in an outdated version of a popular Word processor format – impossible to open on your desktop, let alone on your current portable computing gadget.

Service manuals, internal technical documentation, … are still synonym to FTP downloads, give me your Email and I will send it to you ASAP, Let me send you a CD and the like.

In the more then ten years since I started to do requirements engineering, the world changed a lot, but I am still sitting here in a (really!) top-notch IT company, sending the next draft for review via Email to the customer, using a well intended, but completely unstable documentation template, infested with oodles of unneeded text-styles with strange names.

If a company is already so up-to-date that technical content is made available on the web, it typically involves a not-so-cheap professional publishing toolchain managed by a grown up department full of those bravehearted individuals who spend their time snitching the information from the engineers to pour it into said toolchain. You can literally smell the gap between knowledge, presentation, budget and time to market here.

Heroes to the Rescue

As soon as I heard about the stunning invention from Ward Cunningham – the Wiki – I fell in love with it:

The content is just there: on the web. If something is missing, or outdated, just edit it in place – this concept was ground breaking, not only to me.

At that time the biggest enabler of this simple and powerful idea was Wiki markup: you would just write plain text content, annotate it in a very unobtrusive way and the Wiki software would convert it on the fly into this pesky HTML format required by your browser software. Learning – No, writing HTML is a PITA.

This enabler was leveraged also in other contexts to success: a whole sackload of plain text markups languages have seen the light, Markdown being one of the most popularized in recent years (let's use it as the representative for all others), and this whole family is followed and nurtured by an ever growing industry of products and services which import, publish, process, convert, — whatever you name it — Markdown.

Doing it right

But times and opportunities change, and so does the game:

Is it still true that everybody on this planet has to learn Markdown to be able to take notes, write an internal memo or to publish an API reference?

What if we could directly write in HTML without previous knowledge of it?

The implications would be far-reaching:

You want to take a note. Instead of opening Notepad, you simply open the browser and write it down — headers, bullet lists, highlighting and the whole Unicode character set inclusive.

Whenever you want to read the note, you just open it in the browser. If you want to print it out, you just print it from the browser. If it was a recipe and you did it in the cloud, you go to the supermarket and just read it on your smartphone, striking through ingredient by ingredient as you buy them — in the browser.

Needless to say, that my 150 page requirements engineering document from years ago, as well as the 15-page agile one from last week could as well just be written in HTML. If I send them to the customer — why not just write it in a shared location in the cloud? — they just opened it in their browser and read it.

What would we loose?

There would be no Markdown in your editor, no plain text to HTML or PDF converter no import from foreign format wizard in your word processor, no free read-only viewer software for proprietary documentation file formats.

There would be no middleman, just you, your browser and HTML.

All of it is already there

In fact there is no what if. We can have all of this today, all the ingredients are there.

Since HTML 5 was released by the W3C, JavaScript is an intrinsic, hence standardized, part of it. And thanks to the tireless work of other people there are several JavaScript libraries with which we can edit HTML pages online WhatYouSeeIsWhatYouGet without resorting to an intermediate plain text representation. You have seen and done this already in several occasions on the web.

So why aren't we using HTML as primary documentation format already?

One reason is the security barrier erected between the Internet and the users computer. Browsers by design are not allowed to interact with the local file system directly. Cloud storage providers do not allow to render HTML documents directly. If they did, malicious JavaScript embedded in HTML documents would be able to do anything with our computers or our online accounts.

Another reason for not using HTML is ease of handling. While traditional document formats compact all needed text and media artifacts into one single file, HTML documents — if they are not completely trivial — are collections of several files, which must be packed together for sending, and then unpacked correctly on the receiving side for reading.

Seemingly neither exists a standard nor an accessible software solution for overcoming these impediments for use as plain HTML as generalized document format, apart from a discontinued product from a big software company which once was used for online help files.

The POSHDOC Initiative tries to fill this technological gap – a missing standard and supporting software – under the motto:

Enjoy Writing, Share Easily — Eliminate the Middlemen!