Technical Writing for the Cloud

Technical Writing for the Cloud

By: Eric Sedor
Eric Sedor, a frequent contributor to the Shoap Technical Reader, is a senior software engineer at MongoLab, a cloud-based database provider located in San Francisco. Eric cut his technical writing teeth at Shoap Technical Services before returning to his true passion, software engineering.

The Cloud encapsulates the idea of a distributed system built of formable, destructible, re-creatable components. Even the data within cloud systems is redundant and spread out, capable of being restored in parts to specific points in time, if necessary. Cloud systems even overlap one another.

Cloudiness means agility. Therefore, cloud systems are increasingly less likely to be updated in monolithic transitions that require reorientation and (gasp) reading instructions. Instead, developers release features on the fly—each very quickly but together gradually. Tiny alterations sweep through systems like ripples in a pond. Sometimes there are release blogs and change logs, but many features are revealed with context-sensitive tool-tips or pop-ups.

Importantly, developers are seeking and finding web development platforms that accept and adapt to the inherent unpredictability of the viewable space. Rich user interfaces are found everywhere, even at points of sale. Where documentation is concerned, these systems call for concise, single-source, rapidly visible documentation—something technical writing has struggled to provide well in advance of the cloud age.

Because technical writing has always been about fitting the right content into the appropriate space in the least ambiguous way (while accounting for the user’s point of view), successful technical writing in the cloud age means sticking to technical writing basics and being ready for anything.

Don’t reach for a massive style guide to inform your next project. Try these principles instead:

• Enforce consistency over rule choice –This is more important than ever, because similar content is pluggable content. With content woven throughout today’s applications, a departure from consistency is more likely than ever to stick out like a sore thumb. Whether it is “Click on X”, “Click the X button”, or “Click X”, pick one that’s right for the task, language, and audience. Then stick with it.
• Down with the super-rich – For instructional agility, nothing beats paragraphs, bullets, numbered steps, and basic symbols. Tricky formatting and diagramming endeavors might work miracles in specific circumstances, but such endeavors are the “too big to fail” of modern UI. Paragraphs and bullets combined into a tagged content-hierarchy translate well to all manner of presentation. Every other exotic form should be derived from a tool of the moment, and the best tools of every moment will allow you to maintain documentation in this raw, portable form. Not coincidentally for UX, these basic constructs also scale well to most screen orientations and dimensions.
• Smaller is better – As the viewing space grows, content stops getting bigger and there’s room for more. That means content prepared for the smallest spaces is usable everywhere. Quick-reference card writers have crammed instructions onto tiny stickers since before mobile devices had screens; they know the simplest, clearest language is best delivered using few words. Note “using few words” not “using as few words as possible”. For our purposes, size is about number of words. Be laconic.
• Be wary of description – “Yellow button” and “Bar on the left” were always bad form. In addition to adding clutter, phrases like these are even more likely to mislead as a screen shifts and more likely to become obsolete by accident. For tool tips, rely on context-sensitivity to highlight the region being described; in document form, use current screenshots.

If properly applied, these rules avoid esoteric issues on which various style guides disagree. Because disagreement most often revolves around specific word or punctuation choice, this minimalist style is applied as part of each choice, not as a pre-fabricated set of rules rendered unique by exceptions.

However familiar these rules seem, they form the core of what has been sought by the profession. And they inform the next generation of technical writing without the burden of pedantic 20^th century styles. For best results, select a writing tool with the power to group, sequence, and tag discrete pieces of content, one which can export content to simple HTML and other application-ready data structures (like JSON or XML).

Once you are slinging portable, concise fragments of instruction into rich, scalable user interfaces (while also mapping them to sequential help articles, blogs, and examples), your technical writing will truly join the cloud age.

Good luck!