More exciting than you think. Unless you are already a technical writer, and in that case you were already excited by the idea. Integrated Technical Writing is what folks who decided to call themselves “Content Strategists” have been yearning for all these years.
Yes, I’ve been known to lament that pretty much anyone can slap that label on and prance about calling themselves a content strategist, and it’s true. But if you can find a company whose position is fair and realistic, then integrating content and communication really is that strategy. And it’s fantastic.
I am with a company now, writing proposals for contracts with the government, local, state, and federal, and we GET IT. We totally get it.
I have embraced technical, marketing, and promotional collateral in such a way that I legitimately just put a woman in a sweet yoga pose on the front page of a proposal for the Department of Information Technology for the state where I work. Yes, indeedy. And the tag line is: “She’s flexible, but our standards aren’t.” It’s amazing. And we are going to win a $30 million contract as a result.
We are going to win it because our technical expertise is incredible, yes, but also because we wrote a top-notch proposal that sings marketing through and through.
Integrated Technical Communications has the key language built in:
It integrates the technical componentry with the Communication that needs to be done to sell. And selling is everything. If you cannot learn to operate the machine, the machine is useless.
Sharpen your pencil. Your black or yellow or blue or green pencil. Your integrated pencil. Learn the 5 Ws of online help. Learn the tools of the trade and some design principles. But importantly, learn how they all fit together and have fun blending and blending.
Integration is not just for populations and it isn’t a battle, that’s for sure.
It’s logical and it works, and NOW you can be a content strategist.
No matter what size your company is, or how well-known, I can assure you, every opportunity grasped or missed is the direct, straight-line result of a decision made or a decision delayed.
At lots of companies, decisions get stuck in a pipeline of waiting, approval, hemming and hawing, and sometimes they just die on a vine of withering that is just plain sad to see. Call it bureaucracy, call it checks and balances, call it whatever you like, but it is the companies that are agile, that pivot quickly (stop me if I venture too far into buzz words here, but they caught on for a reason) that survive and even thrive to defeat the others.
Making good decisions, and making them quickly, are the shining coins of successful businesses.
So why is a tech writer posting anything about them? I thought you’d never ask! You see, technical writing has ventured into the deep, lush forest of what now has the lovely, shiny name of “Product Operations” at some of those agile, savvy businesses. Those smart folks took a look around and figured out that the smart folks typing away were…wait for it…learning.
Yes, indeed. And they were right.
We writers have been busy doing, you guessed it, reading. We actually read the stuff we write, believe it or not, and some of it seeps in and we understand it. So when it came time to clear the bottlenecks of business, it sort of made sense to turn to the technical writers who’ve been sitting there reading and writing everything from user guides to employee handbooks all these years and ask them for some insight.
Some of us agreed to offer an opinion or two, and Product Operations was born.
One of the repeated mantras, week in and week out, that I offered to my teams in this process was:
If you oppose, you must propose.
Yep – learn it, commit it to memory. Take it to your teams. Feel free to swipe it. I think I stole it from someone else, and I’m not giving them credit here, so you don’t even have to say you nicked it from me, you can just take it and use it and hog all the credit. (See if it gets you a bit of a promotion or a raise. That’d be nice.)
What it means is, you can point out where something goes wrong – a process, a system, a way of doing things. Go ahead and say it doesn’t work. But then – you have to pony up a way to fix it. We may not use that way, but we won’t ditch it right out of the gate. The most important thing is, you can’t just complain. If you don’t have some sort of solution in mind, even a solution that, in the end, doesn’t fit, you have to keep your trap shut. Don’t point out the flaw until you’ve conjured up a workaround. Even a bad workaround.
A less-than-great decision executed quickly is usually better than no decision executed, or a good decision executed slowly. I mean, a bad decision is going to be a bad decision no matter what. But if you have a brilliant idea but it takes you five years to execute on it, do you really think it was worth it? You can tweak and modify as you go if you just get out of the gate. This is not cutting your bangs we’re talking about here, and even if it was, they’ll grow back. Usually we are talking about developing a new software program or implementing meeting-free Tuesdays. Start building Rome right away. By the time you get the blueprints made, you’ll find the perfect bricklayer, I assure you.
Start mixing mortar.
Right there, that’s the trick. Pick up a stick, or a shovel, or whatever the implement is, and choose. It’s just mortar. You can’t stir it once it dries. So, begin making decisions on a small scale in order to bring about success. As my grandmother once told me, everything can be fixed except death.
I think she might have been exaggerating a bit, so I don’t take it quite that far, but I have determined as a writer that until I hit “send” or “publish,” that I can just decide to write, I can move words around, I can float ideas and concepts, and that to do so is never bad.
In the mode of Product Operations, I started looking at things like information architecture, content strategy, and the blend of systems as a necessary way to get decisions made.
Lo and behold, it worked.
My team began to look at the gaps in our processes and realized that although we each knew what to do when there was a software outage, we each knew what to do when we had to deliver “less than positive” news to a partner or affiliate, we had never concretized that anywhere. So, off we went to create an “Incident Management Guide.”
Similarly, although we had our system down cold for how to manage time and processes in-house, we realized that if a significant part of our team left by, say, taking new opportunities with other companies, the knowledge vacuum would be fierce. The amount of just “stuff” we carried around in our brains about the day-to-day that kept the job pleasant and smooth was astonishing. So we set out to make it a thing. This was despite our tendency as a crew to just be renegade in our approach to daily office behavior, where a meeting was just as likely to be over coffee as it was to be in a conference room. Suddenly, processes and procedures were born.
Some decisions matter, some don’t.
All of this is to say, throughout my years (and they are numerous) I have found that there’s a certain transition from small operation to large, from laid back attitude to not, and back again, that says you somehow gotta put some stuff in writing even when you are pretty sure you don’t. It just makes life easier when you deputize people to have The “D” and to turnaround that decision more easily because they know they can. To build a team with that mojo because it says in a manual (online or in print, with chill or without – you do you) that they can. We built a very nifty team of people, and then we were really able to get stuff done on a big scale by saying, “here’s how we get stuff done.”
I’m just pointing out that it makes life easier if you know:
I’ve been a little focused on failure as the path to success
lately. I think it is because my daughter is graduating from college and my son
is graduating from high school, both in the same year, and both are sharply
focused on what to do next. They are hyper-focused on the need to succeed, and
I am spending more and more time reassuring them that there is more than one
path to success, more than one definition of success, more than one way to
Allow me to meander a bit. We’ll focus on writing in a
My daughter is a talented singer. She attended Ithaca
College for vocal performance. That college is no joke for vocalists. Throughout
high school, she experienced measurable success, though she tried to achieve
more. As a college senior, though, she had a tough time with graduate school
auditions and didn’t gain admission to the schools she wanted – she saw this as
failure. My son is an actor. He attends a performing arts high school, he has
been in more plays and musicals -both amateur and professional- than will fit
on a resume. He was invited to audition for some of the top college
conservatory programs on the east coast, only to be turned down time after
time. He, like his sister, saw this as failure. My heart broke for both of
them, like any mother’s would. They work so hard. They are so well-trained and
educated. What happened? There is no simple answer. But instead of looking
backward, the only way to look is ahead. What comes next? A plan to succeed.
How to turn those downturns into something valuable.
Both kids now have separate paths ahead. My daughter is focused on a year of training and working with vocal students, looking into vocal health and perhaps a conducting MFA in another year. My son accepted an offer from a great college in New York not for theatre, but for film. Once he shifted his view, a whole new picture emerged. Actors are in movies, after all.
So on to writing…
I’ve written plenty of documentation that misses the mark. I have to go back to it and rethink, rework the process until it hits. I read the work of Nobel Prize winners Daniel Kahneman and Amos Tversky, who articulated how important it is to feel insecure, to lose, to get things wrong. (I am far oversimplifying this but the gist is – you must fail.)
As people, to succeed, we have to embrace failure in order to succeed. Tech giant Jack Ma spoke at the World Economic Forum in 2018 about his failure when he applied for a job at KFC. 24 people applied for positions, 23 people were hired. He was not one. He applied to Harvard 10 times. He was not accepted. 10 times! Talk about really wanting something! Failure hurts, indeed, but we learn from it. It’s normal and maybe we should see it as a little less detrimental and harmful if we can start to view it as part of our growth. (I still doubt that I would apply ten times, but…)
I recently read H. Jon Benjamin’s “Failure is an Option”
while on a road trip. Seriously funny stuff, that book. Part memoir, part joke,
the whole book had me in stitches. If the guy who blends Archer and Bob’s
Burgers and landed in a big pot of wealthy can’t talk to you about failing, who
else can? And he can write, too! As a writer, I respect that. I brought his
thinking to my writing, and to my workplace. He may not be drafting technical
manuals, but the point is still the same. You can reinvent text, yourself, your
path, and your work. Failure IS an option. Just don’t flog yourself over it.
Don’t make it a habit, unless you are a comedian, and then if you are, write a
book about it and cash in on the whole life experience.
Henry Ford is thought to have said “failure is the opportunity to begin again, more intelligently.” And I’ve read that it took Dyson vacuums 5,127 prototypes in order to arrive at that amazing, ultra-successful 5,128th model that we are willing to pay a handsome fee for – all to have a great experience.
Workplaces that penalize failure wind up with low-talent, low-energy responsibility-shirkers. In technical writing, and in any kind of writing, it is taking a risk, being willing to innovate and develop new methods, new approaches, and new techniques that blazes a new path to truly dynamic customer experiences.
Our work is integral to our lives. Our successes are integral to our work. What we do defines who we are, whether that is our job, our home life, our sports or our pastimes. When there is opportunity in decision-making, there is risk and there is reward (unless there isn’t).
So, dear writers, break out the pen, not the safe pencil
with the eraser, and make yourself uncomfortable. Mess it up. Then fix it. Then
learn from it. Fail…to succeed.
Back when I was an undergrad (please do not stop and linger
long enough to consider how long ago that was), and I declared that I would be
an “English major,” that declaration struck fear in the hearts of many. It did
so because to those not-so-intrepid folks, that meant I believed, in folly,
that I could write the Great American Novel, or that I would be content living
a life for a few years as a starving poet, only to eventually cave in and
become a teacher. My mother was a high school English teacher. Her mother was a
sixth grade English teacher. The path appeared to have been laid.
I, however, had no real intention of becoming a traditional
high school English teacher. I did enjoy a stint for a two-year period as a “teaching
artist” at a performing arts magnet school where I had the luxury of teaching creative
nonfiction for two and a half hours each afternoon, but I seriously cannot put
that in the same bucket as mapping out rubrics for Huckleberry Finn or Hamlet for
Instead, that time provided me with a fantastic foundation
for my own writing, which I still do (you are reading some of it at this
moment), and the luxury of my mornings free. It was a great time. It launched
me into other cool projects, and I got to work with aspiring writers without
ever having to get my teaching certificate. I’ll take that as a win.
I moved through writing positions, always knowing what those
early doubters knew: people think writing is easy, until it isn’t.
It is only in fairly recent history that writers have
dovetailed so well with users and designers. (I have another post about this,
so take a look at some older posts and you’ll see my position on UX and writing
– I was ahead of the curve!) User Experience, or UX, was for a while considered
to be a design concept, not a language one. Few people thought that the words
themselves contained meaning. Most believed that an arrow was just an arrow –
it could point users to what they needed, and whether it contained text was of
no importance. That is, we thought that it didn’t matter what the pop-up or tab
had written on it, just that there was a pop-up or tab. It’s not until we had
dozens of those tabs from which to choose that things got murky.
But those of us who focus on words intervened to disagree.
We started to ask, would users rather “click” or “select?” Is it a “flyer” or a
“flier?” Are we really going to have yet another discussion about “dropdown”
versus “pulldown?” We absolutely are going to have that discussion. And our
customers will be glad we did. That disruptive error message a user gets – if
it isn’t too disruptive, a customer won’t give up on using the software we have
so lovingly designed. So, while marketing copywriters are diligently working to
bring us customers, if we as tech writers and UX writers ensure a smooth
journey through the software, we can keep those customers around for a long,
long time. They will have had meaningful interactions with our product and our
Let the marketers worry about conversion. Let the us, as UX
and Tech writers, worry about facilitation.
One of the things I have enjoyed most about technical writing
is just that – facilitation. I often say that a big part of my job is “smoothing
out the pain points” for those who use my software. I joke that no one reads
the doc, but that is not entirely true. They read the doc when they have a
specific need. That need is at installation: when they are brand-new and want
to ramp up fast. Or, they read it when they hit a trouble spot: they want a
solution to a problem. But there is a whole lot of “doc” in the interim, and
that doc is within the product itself – the entirety of the product design
contains compelling microcopy (or sometimes the microcopy is the opposite of
compelling, let’s be honest). Prioritizing the user journey not just visually,
but textually, a good writer can work with a good designer, and hit the jackpot,
Extremely good UX means an extremely satisfied customer. A
customer whose needs are highlighted by thoughtful text is one who sees a
compelling product, I assure you. I feel the same way about technical documentation.
If the tech doc supports a well-crafted product, and supports it concisely, there
is little need for a stressful support call. Not all software (or any other
product, for that matter) can be so well designed that it needs no
documentation whatsoever. What we must do as writers in all realms is to create
an experience, from microcopy to large-scale content, that is smooth and clean.
If we do that, we’ll have done our jobs well. We will have made not just copy,
A conversation with a (junior) colleague this morning started off with “How did you decide to reformat your Best Practices Guide?” and moved on to things like “But how did you know that you should be working in Artificial Intelligence and VUI for this search stuff? I mean, how do you know it will work?”
I couldn’t help but chuckle to myself.
“Rest assured,” I said. “Part of it is just that you know what you know. Watch your customers. Rely on your gut. But more importantly, trust the data.” The response was something of a blank stare, which was telling.
All too often, tech writers – software writers especially it seems, although I do not have the requisite studies to support that claim – are too steeped in their actual products to reach out and engage in customer usage data, to mine engagement models and determine what their users want when it comes to their doc. They are focused on things, albeit important things, like grammar, standards, style guides, and so on. This leaves little time for customer engagement, so that falls to the bottom of the “to-do” list until an NPS score shows up and that score is abysmal. By that time, if the documentation set is large (like mine) it’s time for triage. But can the doc be saved? Maybe, maybe not.
If you’re lucky like I am, you work for a company that practices Agile or SAFe and you write doc in an environment that doesn’t shunt you to the end of the development line, so you can take a crack at fixing what’s broken. (If you don’t work for a rainbow-in-the-clouds company like mine, I suggest you dust off your resume and find one. They are super fun! But, I digress.)
Back to the colleague-conversation. Here’s how I knew to reformat the BP Guide that prompted the morning conversation:
I am working toward making all of my documentation consistent through the use of templating and accompanying videos. Why? Research.
According to Forrester, 79% of customers would rather use self-service documentation than a human-assisted support channel. According to an Aspect CX survey, 33% said they would rather “clean a toilet” than wait for Support. Seriously? Clean a toilet? That means I need to have some very user-friendly, easily accessible documentation that is clear, concise, and usable. My customers do NOT want to head over to support. It makes them angry. It’s squicky. They have very strong feelings about making support calls. I am not going to send my customers to support. The Acquity group says that 72% of customers buy only from vendors that can find product (support and documentation) content online. I want my customers’ experience to be smooth and easy. Super slick.
In retail sales, we already know that the day your product is offered on Amazon is the day you are no longer relevant in the traditional market so it’s a good thing that my company sells software by subscription and not washers and dryers. Companies that do not offer subscription models or create a top-notch customer experience cease to be relevant in a very short span of time thanks to thanks to changing interfaces.
I’m working to make the current customer support channel a fully automatable target. Why? It is low-risk, high-reward, and the right technology can automate the customer support representative out of a job. That’s not cruel or awful; it’s exciting, and it opens new opportunities. Think about the channels for new positions, new functions that support engineers. If the people who used to take support cal
ls instead now focus on designing smart user decision trees based on context and process tasks as contextual language designers, it’s a win. If former support analysts are in new roles as Voice of the Customer (VoC) Analysts, think about the huge gains in customer insights because they have the distinct ability to make deep analyses into our most valuable business questions rather than tackling mundane how-to questions and daily fixes that are instead handled by the deep learning of a smart VUI. It’s not magic; it’s today. These two new job titles are just two of the AI-based fields that are conjured by Joe McKendrick in a recent Forbes article so I am not alone in this thinking by far.
His research thinking aligns with mine. And Gartner predicts that by 2020, AI will create more jobs than it eliminates.
So as I nest these Best Practices guides, as I create more integrated documentation, as I rely on both my gut and my data, I know where my documentation is headed, because I rely on data. I look to what my customers tell me. I dive into charts and graphs and points on scales. The information is there, and AI will tell me more than I ever dreamed of…if I listen closely and follow the learning path.
So. It’s just after the holidays, and a whole slew of people opened a new Amazon Echo or Google Home brought by a jolly elf as a gift. Now, they are rolling their eyes or scratching their foreheads over the responses they get from their supposedly smart home assistants, or (if they are like one of my office colleagues) they are claiming the thing is trash, but perhaps better, they are praising the heavens and enjoying the heck out of artificial intelligence and Voice-User-Interface. Hallelujah for converts!
Many along any point on that spectrum are wondering how the heck it could be so difficult to get that stuff right, and many of you, dear readers, are wondering what this has to do with the price of peas and technical writing.
You see, a few weeks ago, my development team here at my office had what we all an “innovation sprint.” That is where we get to blow off some steam and quit working on our traditional run of the mill development tasks and think, instead, about the kinds of things we would do if we didn’t have customer deadlines and goals. We get to open up our imaginations and play around a bit – so what we did was to imagine what would happen if we could get something like the Amazon Echo to talk to mainframe computers and therefore get mainframe computers to talk back to the Amazon Echo – the ultimate in automation processes, as it were. Now mind you, the entire team does not have to participate. This process is totally voluntary. Team members can catch up on overdue work or sketch out other projects that they may want to work on in the future. They can conceive of ways to make their workdays easier or to otherwise improve the customer experience, that sort of thing.
But I was sticking with the Echo. I did not think it would work, but I am a glutton for impossible tasks.
I was right, and we failed fast. Too many security issues, turns out. But what did work, and what tickled me to no end, was that it IS possible to ask the adorable Voice User Interface to search my well-crafted user documentation (a tome that would be some 6,000 pages if it were printed, mind you) for any string of words or numbers that you wish to find, and the marvelous Alexa can be taught to return results with alarming accuracy. Voila!
Just like Alexa can learn movie trivia or what time the bus will arrive at my stop, just like this model of artificial intelligence can archive my weekly grocery list and take on my daily calendar or read each day’s news from a variety of prescribed sources, this cylindrical wonder will root through those words upon words upon numbers and more words, and even acronyms and reveal the right answer time after time. Once we program her.
In addition to these innovation sprints, my company also supports a project called the Accelerator. Think “incubator” but with less risk. A gargantuan company helping to nurture fledgling startups. It’s pretty great. First there is a rigorous application process and proving ground, naturally, but once you’ve run the gauntlet, it’s quite the ride – a supported startup, if you will. And that is where I am headed, my Alexa by my side.
A technical writer’s dream, and maybe nightmare, all at once.
It seems I have opened an oyster of sorts.
I found a path to documentation using VUIs, a search tool for the largest documentation set with which I have worked. And after all, the Alexa was named after the Library at Alexandria, so it stands to reason. I am pleased as punch. Let the innovation continue, and the documentation shall “speak” for itself.
So very often I hear about how tech writing is a dying industry, and it makes me sad. Then, I remember that our name has just changed. The bluster is just bluster. We are content managers, information engineers, media strategists, and so on. The funny thing about some of this rebranding is, I recently looked on Glassdoor, and learned that, depending on what you call yourself, the salary for those titles varies widely.
For example, the average “media strategist” nationally is clocking in at $46,736, while the national average for a “content strategist” $70,000. I’m wondering what the huge distinction is, to be honest. And, I can admit that I don’t really know. My work title is information engineer because I am in a company full of engineers. We make software, we build solutions in the fast-paced software world, so my work is a little more specialized. If you want to know the national average on that salary, I’ll let you do your own research, and then I’ll reassure you that I am not making what Glassdoor says.
I looked on Wikipedia, and the generalist definition of Information Engineering is that we take a software engineering approach to writing and developing information systems, or that mostly we are computer geeks who write. Well…I’m actually a writer who enjoys software systems. I was hired to work specifically on mainframe systems even though I knew almost nothing about mainframes when I joined the company. I think the big distinction is that, as writers, we know how to communicate complex information and that we have knack for learning things. Definitely if I was not into learning, I would stink at this job. But what actually separates me from a “media strategist” in terms of my skillset? That is to say, what if I wanted to leapfrog from my current job into media strategy? Am I working on the tools that might be portable enough to move from one position to another? Yes. And you should too.
In this field, I argue that it is critically important to continue honing not just the technical acumen, but the strategy, to keep abreast of what is going on in other writing areas in order to be as portable as possible. My specific company is using what might not be considered the most cutting-edge authoring tools, so I make sure I learn some techniques and tools outside of my daily grind in order to stay on top of what’s out there elsewhere. So, if you are in a particular niche, say Information Engineering, it is not an altogether terrible thing to make sure that you know that a “media strategist,” for example, is an increasingly complex role that puts you in charge of content delivery in broadcast arenas. Knowing this, in my role as a software documentation writer, I step up on a regular basis and record videos, work with a program called Captivate (an Adobe product) and just play around with what is out there on YouTube in instructional video land. Admittedly, this is never going to put me in the C-Suite of media strategy, but neither is it going to leave me looking like a gasping fish.
Likewise, I try to keep tabs on other media and collaborative tools like #slack or Asana for collaboration tools. If you are knee-deep in managing content projects, you’ll surely want to be adept with these beauties, or at least one of them. My company is currently using Flowdock. It’s not my favorite, but it is a powerful tool, proven with doc-sharing and it gets around. Some companies are making great use of Yammer as a powerful intranet communication device as well. I recommend at least having a working knowledge of these gadgets. You can’t go wrong, and a broad skills base is never a bad thing, right? Right.
What about the idea of content strategy, you say? These things lean on media management. A recent post was about content, and I daresay I could reiterate that everything I do is about content – content is text, video, graphics, interfacing all of these things into a usable, consumable, findable set or even suite of instructions and understandable items that users can then put to use, find again if necessary and move on if not. From an installation guide to a set of scenarios for implementation to third-party software agreements, it all has to be chunked into usable bits of information in the best way(s) possible, and it is up to us – the wordsmiths, the video script writers, the graphic designers, and the UX specialists, to get it right. And often, more and more and more often – we are the same person.
I suppose all of this goes to say that in the pool of tech writing tools, we aren’t supposed to stay focused only on the items that specifically make us “tech” writers. So grab that pint and start spending part of your day – every single day – finding what’s out there to make you the best writer, editor, designer and consumer. Because that is your new name. It’s been mine for a while. Communications specialist? A rose is a rose is a technical writer is a media strategist is a content implementation designer. All I know is I craft exceptional messaging every day.
In my not-so-distant past, I read an article by a writer, who posts things in a forum which I respect, pleading that we no longer call our writing Content. She ruminated deeply on this topic, outlining reason after reason why we should respect writing enough to ditch this term, (she called it a “catchall”) and give ourselves the respect that we deserve. She argued that there was, in fact, no way that a writer came up with the term “content” to describe what we put into phrases and paragraphs every day for a living.
I felt maligned. Insulted, even. My feelings were hurt partly because I am currently pursuing a certification in Content Strategy. Yes, content. I rather enjoy thinking of my writing as “content.” While I agree that there may be more nuanced terms for some forms of writing – and we may be more specific: poetry, haiku, essay, short story, etc., in the world of technical communication, marketing and corporate communications, what we create is…wait for it…content. But I was more bent out of shape because when asked, I introduce myself as a writer. I rarely qualify this term unless I need to.
I am a writer.
The words, phrases, and paragraphs that I construct are inextricably linked to a perception of the company for which I work, its products and its mindset. What I write for them is not the great American novel, nor do I wish it to be. This writer argued that “to write is to find out what you think.” How very noble. I wish that I was finding out what I am thinking while I am creating dozens of web pages that instruct software users in the intricacies of an installation process that is many steps long and requires detailed diagrams to accompany my flowery prose. Alas, I am not. What I am doing is creating useful, tangible prose that goes out into the world and does real good. My writing takes root, grows, and from it blooms a garden of procedures. Those procedures help make sure that your debit card works every Monday morning. It’s a beautiful thing, but I won’t be nominated for a Pen Faulkner any time soon.
Because I create content.
She even maligns content as a marketing strategy, which I found specious. I generate literally dozens of tweets per month in order to forward the ideas and goals of my company. That is writing – and it’s hard writing. I have to be creative, pithy, sometimes funny, sometimes I do a lot of research – and all in a very tight space. It’s called brevity, and Mark Twain said that was the soul of wit. I’m with him. And it’s writing. It’s writing content. That content helps users get to my products and helps people understand my work. Plus it’s darn good writing. So there.
People consume my content, not the way they consume a classic novel or even a beach read. They do not recommend my work to their friends as the next great thing to read, and they do not say, “Hey, did you see that great process that Susan just created? Wow! Talk about incredibly lean doc!” That, my friends, is the dream of any software documentation writer, I assure you. But maybe, just maybe, what some of my friends say is, “Susan wrote an insightful blog about the value of Content Writing and how it is important, just like writing your memoir. After all, that technical document will show you how to set up your new laptop so that you can write your memoir. And then you can stick your nose in the air and claim that is real writing, not merely content.”
“working software is the primary measure of progress” and the manifesto values “working software over comprehensive documentation.” That is all well and good, but as a writer, I often pause on that one word – comprehensive. I take a moment there and wonder who determines what comprehensive means, and whether sometimes we leave the customer, and the customer’s needs, in the dust when we use that word.
Before every developer everywhere has a head explosion, I think we can all agree that expansive documentation is silly and frivolous. So maybe I would swap out comprehensive for expansive. Perhaps I’d have chosen “frivolous documentation,” or “needless documentation.” I’m just not sure I would have chosen the word comprehensive. I get what the manifesto is going for. I do. I want to create lean, usable doc every time. I don’t want to give more than is needed. I want to respond to change fast. My goal is accurate, deliverable doc that addresses stakeholder needs. I suppose I would like to think that, by definition then, my doc is complete, or…comprehensive…in that it includes everything a customer needs. But I agree that I don’t want it to include anything more. I just want to avoid coming up short.
What if I rewrote the twelve principles from a doc-centric focus? Would they work just as well?
My highest priority is to satisfy the customer through early and continuous delivery of valuable documentation.
Welcome changing requirements, even late in documentation. Agile processes harness edits for the customer’s competitive advantage.
Deliver accurate documentation frequently, from a couple of weeks to a couple of months, with a preference for the shorter timescale.
Business people, developers, and writers must work together daily throughout the project.
Write documentation around motivated individuals. Give them the environment and support they need and trust them to get the doc written.
The most efficient and effective method of conveying information to and within a writing team is face-to-face conversation.
Clear, concise documentation is the primary measure of progress.
Agile processes promote sustainable writing. All team members should be able to maintain a constant pace indefinitely.
Continuous attention to linguistic excellence and good design enhances agility.
Simplicity – the art of maximizing the amount of writing not done or words not written – is essential.
The best architectures, sites, and manuals emerge from self-organizing teams.
At regular intervals, the team reflects on how to create more effective doc and then adjusts accordingly.
Okay, so some of this is silly, and I just wasted twelve lines by playing it out all the way to the end, but it was for good reason. Continuous deployment can happen not just with developing software, but in the embracing of documentation as part of that software, but instead it is often “kicked to the curb” by many teams as a misinterpretation of that one element of the original manifesto.
It’s not that documentation should be cast aside; it’s that comprehensive documentation is being misunderstood as frivolous or extraneous documentation.
I did not realize that this was a pernicious issue quite so much until I was giving a workshop to a small class of new developers from across my company, hailing from a variety of offices, and they looked at me funny when I described some of how my team does doc (we are pretty good at the whole agile thing, but sometimes we regress into “mini-waterfalls” and I hate them). One of the young devs was astonished that I manage to get my developers to hand over documentation early in the process so that I have it in a draft state, while the code is still being written, not after the code is all in place. It’s a struggle, I’ll admit, but when I this happens, the result is a joyous celebration of shared workload and well-written doc. We can collaborate, change, shift and learn. And the sprint goes more smoothly with only minor changes at the end, not a doc dump in week 4.
To teams who are not doing this: cut it out with the waterfall, guys. Doc is essential, and your users need it. Otherwise, they are calling support and costing your company thousands with every call. Change your practice and build your doc while you build your product.
You might be asking, “How can you possibly write the doc when you haven’t written the code?”
You are not the first person to ask this, trust me. The answer is pretty simple. A long, long time ago, you couldn’t. Or, at least it wasn’t wise to, because it was a redoubling of work. When writers put their stuff into pdfs or word documents, and then had to make major changes, it meant a bunch of editing and rewriting things. Therefore, developers got in the habit of writing all of the code, then examining the processes and hunkering down to crank out the doc. Fair enough. Now, though, we developed wiki spaces and collaborative tech writing tools that now allow inline editing and let developers look at the cool formatting and linking that tech writers have done with our work.
And – before the code even gets written, there is a design plan in place, and usually a design document to go with it. There are code specifications, right? You can have a nice chat with your friendly tech writer and go over this, either through a face-to-face (see Agile point #6) or via any of the vast number of other tools designed to communicate with your team. Before a developer starts coding, there is a project plan – share that plan. Once the general information has stabilized, it’s okay to let the writer have at it. The benefit is that the writer is having her way with the general plan while the developer is coding away. At the end of both work days, the writer and developer have each created something. In a typically short iteration, it is unlikely that the coding will change significantly, so the two can touch base frequently to mark changes (See Agile point #4).
Are there risks to this process? Of course, just like there are with waterfall. Remember that with waterfall, there were a fair amount of times that programming crept right up to the deadline and documentation was hastily delivered and could therefore be sloppy and lacking. And in this method, it is far easier to tell you about writing documentation continuously than it is to actually do it. It takes time, it takes effort, and it takes dedication – because the primary risk for doc is the same as it is for the software: that the customer’s need will change midstream. That problem was (more or less) solved by short iterations in development, and it is (more or less) solved the same way in documentation.
The benefit is this – by writing the doc alongside the development, you can be sure that you deliver the doc in sync with the product. You’ll never sent the product out the door with insufficient instruction, and you will never cost your company thousands of dollars in support calls because your customers don’t understand how the product works or how to migrate it. But deliver a product without comprehensive – yes, I’m back to that word – deliver it without a complete doc set, and you may regret it. Trial and error is okay if you want to see how fast Mario can get his Kart down the hill in order to beat Luigi and save the princess, but do you really want to rely on that when the client is a multi-million dollar bank?
I’ve been teaching writing and writing processes for a very long time, and believe me, the action of draft, revise, revise, revise is not new.