Simplex Veri Sigillum

Keep It Simple, Stupid - in Latin. (Literally: simplicity is the seal of truth).

When it comes to producing documentation (heck, software), simplex veri sigillum far outstrips the inane concept of "RadioUserland for Dummies". Alas, I doubt simplex will market as well!

Attaining simplicity is not the first thing but the last thing to be achieved in any discipline. Michael Jordan, Luciano Pavorotti and, to some extent, Userland, have met the test.

(Software is still too embryonic an art-and-science to affirm simplicity as a goal. Feature bloat is the refuge of those who are too insecure to be simple).

William of Ockham defined his version of simplex as pluralitas non est ponenda sine necessitate - "plurality should not be posited without necessity." He must not have been a Windows user.

Simplicity is not a goal in itself but it is indeed a goal. Radio, understood as a platform, embraces extraordinarily complex functionality within an appropriately simple framework. This does not mean that mastering Radio is necessarily easy. Simple thing can be most challenging.

For Content

Great documentation respects the design of the software it would narrate. It writes to the level of that design, not the presumed level of the reader.

Don't mistake me.

Documentation must translate and re-present that design-with-its-implemented-features so that any reasonably intelligent human being can make sense of it. However, if the doc isn't faithful to the underlying philosophy of the software, users will sense a mismatch. They will turn away from the documentation and - often - the product.

Simplicity in content, therefore, means that we explain how to use a product in the clearest, most straightforward way consistent with the power provided by the software at any given point.

When I explain how to understand and use the dashboard of a car (or the user interface of Radio), simplicity takes on a different flavor than when I explain how to repair (or let us say, customize) the engine of that car (the underlying desktop application of Radio).

For Style

I find it very tempting to use stylistic gimmicks when writing documentation. This is no different than the temptation native to all writing - films, novels, nonfiction, documentation and, for that matter, programming code.

A fine sense of style is vital. It does not contradict the dictum for simplicity. Still, style should hide modestly behind content. When a reader "sees" the style rather than the content, simplicity has been surrendered for something less than itself.

Style must coincide with the varied nature of a given medium.

Weblogs are, by nature, highly personal. I will write documentation in my weblog in a different style than I would in a printed book. Indeed, we have not yet understood how to do this well on the Internet - learning how is one of the goals of my weblog.

Since documentation is not a diary (well ...) or a rant (but ...) or a review of other linked documents on other sites (hmm ...), I suspect that great documentation style online will be personal but more subtle than we find on your prototypical weblog.

You want to learn how to use Radio and maybe Frontier or Manila as well - not discover what I had for breakfast this morning.

(Okay. Coffee. Old-fashioned steel cut oatmeal with raisins, butter, cream and brown sugar. Yum.)

For Collaboration

Online documentation of a product like Radio cannot be simpler than its vision of an online community where the sum of the knowledge shared is greater than the (weblogs of its) parts.

Radio's documentation grows every day on the Internet. It evolves as a distributed dialogue between its users. The documentation iceberg 'tips' offered by Userland must always be the least interesting - and useful - view of the berg itself.

This may be why Userland's John Robb envisions the products as knowledge logging tools. However, understanding how to communicate this to current and prospective users is tough as nails for Userland, or at least, for me.

Learning how to collect, index and augment Radio's documentation will even tougher.

Yet, doing so is, in my opinion, at the very core of Userland's current mission.

If Userland (and I include the entire community here, not just the company) can't K-Log its own product lore, how can it hope to evangelize rich use of the products into other knowledge communities?

Now, this is not a simplex task. But then, as Einstein said, "Everything should be made as simple as possible, but not simpler."

Right.

Happily, just because some things in the universe, let alone Userland's universe, may be irreducibly complex does not mean they cannot be approached, touched, used and appreciated.

Even documented.

Consult my site index as you begin your journey. Better yet, help me refine my own road map. It's your road too.

 <-- Return to Home Page