Right now.
Don’t feel it? Are you shackled to tools, processes, or output formats that feel like they belong to another age, like the Jurassic?
I struggle with this myself. A lot of my users want PDF. Sometimes they demand it in their contract.
Producing release after release of static PDF manuals is not my favorite part of the job. Mind you, it’s still good work, valuable day-to-day work that needs to be done, and I’m fortunate to be doing it. My years spent slinging take-out teriyaki and lying under pickup trucks in icy water hooking up rental trailers remind me how lucky I am.
Even so, we all have our down days, like when I’ve been grinding on release notes or making painstaking, incremental updates to existing doc. These times make me wonder if there’s something more I could be doing. I yearn for more engaging solutions to meet my users’ needs.
In my yearning, I search out inspiration and I find it in a glittering tech-writing landscape brimming with ingenious people and enlightened groups who are working on that “something more” for my users and me, cultivating attitudes and developing processes that I can incorporate into my workday.
Doc of Ages
Why declare a Golden Age? First some context from previous ages to put the current age in perspective (all dates approximate, expressed in CE, and somewhat arbitrary):
Stone Age ( -1939): Tribal knowledge ruled (and still does in the dark places of many organizations). Information flowed directly one-to-one from elders and experts through mentoring and apprenticeship. The classroom model brought late-age innovation in the form of one-to-many information transfer. Documentation existed in early forms such as maps, cookbooks, style guides, textbooks, and other didactic works.
Bronze Age (1939-1980): With World War II came the need to train large numbers of nontechnical people to use increasingly complex and technical equipment as quickly as possible. The outcome of the war depended on how well they learned. In addition to textbooks for classrooms, maintaining complex equipment spawned modern reference manuals. Media technology remained traditional typesetting and illustration with some innovation in photography and film. The growing volume of information spurred development of theories and methodologies for analyzing, organizing and presenting information, like cladistics (1958-1966), Information Mapping (1969), Tony Buzan’s “Mind Mapping” (1974), and Jacques Bertin’s Semiology of Graphics (1967).
Iron Age (1981-1991): Advent of desktop publishing tools like Interleaf and FrameMaker. Technological revolution in technology writing. Online help. Nascent Internet.
Silver Age (1991-2011): Writers shift focus from content production to resolving challenges of content management and delivery with solutions like single source and Darwin Information Typing Architecture (DITA). Context sensitive help. World Wide Web.
The Golden Age
Which brings us to the current age (2012- ) and what I’ve seen in recent years that makes our time so special:
- Continuous Delivery (CD) applied to documentation: CD is a software development methodology that focuses on getting changes in the product into the hands of users, safely, quickly, and in a sustainable way. CD for docs involves a change in mindset. Documentation is no longer a static and obsolete-before-release byproduct of the development process. The doc is never “done”. Change is constant, driven by changes in the underlying product, the desire to optimize the content for the user, or simply to fix bugs.
- Doc as Code: A natural complement to CD, Doc as Code is “a philosophy that you should be writing documentation with the same tools as code”. For many products and services, the documentation is the product. For example, for many service providers, the primary interface between the company and their users is an API and the doc that explains how to use it. Doc as code acknowledges and encourages this close association. Using the same tools as the code opens the possibility of a healthier, more productive relationship between developer and writer. Instead of working in their separate worlds with their mutually exclusive tools, developers and writers can truly collaborate. The source code, issue tracking tools, and version control are a shared workspace for the developer and the writer to author, review, comment, and edit. For more info, see the Doc as Code page.
- Applied empathy: From my previous column on the subject: Empathy is “the ability to sense other people’s emotions, coupled with the ability to imagine what someone else might be thinking or feeling [that] helps us understand the perspectives, needs, and intentions of others.” Applied empathy bolsters that “ability to sense” with actionable data. Imagination is enhanced with metrics, feedback, and analytics so that you can create useful documentation informed by your understanding of users’ perspectives, needs, and intentions. For more details, watch Kat King’s excellent talk at Write the Docs Portland that inspired me.
- Wholistic documentation organizations: My experience with professional groups of previous ages left me a little wanting. They felt self-involved, reinforcing the prevailing “us vs. them” attitude of writers against the world (engineers, market, sales, management), and were preoccupied with their own organizational integrity and internal politics. I feel more comfortable in a group like Write the Docs, which is inclusive of anyone and everyone who values good documentation. No matter whether you’re a writer or an engineer or an executive, if you value documentation, you belong and you are encouraged to contribute.
A common thread running through the Golden Age signals a shift from documentation-centric to user-centric. In previous ages, it was enough to collect and organize information. The user was left to RTFM. Now we’re not writing doc for its own sake. We understand that just having documentation is not enough. Our doc must be available, fresh, and helpful.
This evolution in thought is encapsulated by how I’ve changed my answer when people ask me “What do you do?” In 1997, I said “I write manuals”, which was usually interpreted as “I write those fat stacks of dead tree that your monitor sits on.” Now I tell folks “I write the stuff that helps people get things done.”
What Does It Mean to You?
So what can you do with all of this? How can you and your users benefit from the golden glow of this new-age doc stuff?
I’m no Da Vinci or Descartes of documentation. Not everyone can be or even wants to be. Positive change doesn’t require genius or revolution. You can make positive changes in big ways and small with the resources that you have on hand with solutions that are well within the reach of any tech writer, whether you’re a lone writer or part of a large team.
It’s the Small Things
For an example of small-scale change, take a 437-page Admin guide from my doc set. Even that old, stuffy PDF can benefit from a sprinkling of Golden Age pixie dust:
- Applied empathy (data): How do my users use the guide? Does anything need to change? If so, what? The static, monolithic nature of PDF precludes me from building in topic- or workflow-based usage tracking. I’m not saying it’s impossible, just beyond my capability and budget. Instead, I’ve added Google Metrics to my doc distribution site so, at the very least, I get usage stats like how many times the PDF was downloaded, when, and from where. I then use these stats to gauge demand, set priorities, and allocate my time. The metrics show that the Admin guide sees a lot of use, so I feel justified in spending time on it.
- Applied empathy (feedback): 437 pages is overwhelming. User feedback confirms common sense, with my users telling me the doc is unwieldy. How can present this behemoth to make it less intimidating? I would like to break it down into smaller documents by use case, but multi-file PDF is problematic. Based on observation, my users jump to full-text search before spending any time on navigation aids like menus, table of contents, or indexes. Can I preserve that precious full-text search? Turns out I can. I’m currently implementing a free third-party search tool (elasticsearch) with PDF indexing so that I can decouple full-text search from content structure and presentation.
- Continuous Delivery: If the doc is never “done”, how do I ensure that my users get the freshest PDFs hot off the virtual press? PDF generation does not allow for the atomic-level changes that are a hallmark of typical CD. To compensate for this, I’ve automated the heck out of PDF building and deployment. I don’t collect fixes and changes for our biweekly product releases. Build/deployment is so fast and easy that I can make edits as they come and redeploy in seconds. But it’s not enough to have fresh content. I need to get the new stuff into the users’ hands, so I built a doc distribution website and trained my users to look to it for their single source of the latest truth in doc.
The Big Things
If you feel stuck in a Documentation Dark Age and you’re looking to go big on enlightenment, I strongly recommend that you reach out and find an industry group that fits you.
For introverts, this can mean a big expenditure of time and emotional energy. For extroverts, there’s no getting around the time expenditure (participating on the group’s social media, attending meetups and conferences). Depending on how far you have to travel, conferences can be expensive as well, a big hit to your pocketbook if your employer doesn’t help out.
Despite the costs, the benefits can be huge for both lone writers and team writers. Lone writers get an instant community of like-minded folks, a hive-mind incubator of ideas, and a support network for tools, technology, and mental health. If you work in a team of writers, the benefits can be just as profound. Companies develop their own cultures. Sometimes it can be difficult to see beyond the traditions and rituals of company culture. I guarantee you that participation in a vibrant industry group will help you by affirming the good processes and identifying the traditions that have calcified beyond usefulness.
Finally, if your current workplace isn’t satisfying your need to write cool and useful stuff, maybe it’s time for a big change and find some greener pastures. They’re out there. I’ve seen them.
Where Do We Go from Here?
Is this the end? Is this as good as it gets? Do we finally have all the answers? Of course not.
None of these Golden Age philosophies or the tools and processes they inspire are a complete solution. There is no magic bullet.
Users’ needs don’t change much. They need to know how to do something and they need it now. Innovation comes with how we recognize and meet those needs. There will be a next wave of innovation.
I’m already looking forward to documentation’s Diamond Age.
