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 20th 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.
2 replies on “Technical Writing for the Cloud”
This is definitely an issue, both for writing style and for delivery. That’s why I’m working on an open source framework for Distributed Dynamic Document Display or 4D Pubs. The idea is to assemble a document set at the lest minute, bringing a collection of references together in the client that acts like a single doc set. Each service node stores raw XML and a manifest. Any manifest can include links to topics stored on another service node — that way, if my service uses your API, then my docs can include your docs. All the merging, assembly, and transformation happens in the client at the list minute.
I already have an initial version of this functioning in a shipped product. I can filter by user role, call the product API to load state information into the content, or even drive the product from the documentation. As we add new products to our offering, I’ll build in the doc merge capabilities. The infrastructure is already in place and working.
Cloud, virtual infrastructures, client/server architecture… It’s a brave new world.
Thanks, Chris. It sounds like 4D Pubs is exactly the sort of product referred to above. Wonderful stuff; good luck taking it even further!