Back Off, Creep!


Image result for back off creep

Why do Technical Writers Care About Scope Creep?

Typically, Scope Creep is defined loosely as adding additional features or functionality to a new product, or adding unauthorized work to a project in progress, thus adding to the “scope” of the project that has already been defined – that is, adding to the “scope.” Adding functionality to software will, for example, add additional development hours and while it might make for a better overall product it will increase development time and cost, and it might even be more than the customer asked for or was expecting.

Imagine it this way – you hire a contractor to build you a lovely kitchen. You agree on cherry cabinetry with stainless-steel handles that have been ordered from a warehouse and you have provided the contractor with your drawings for how those should be installed and where. You like your design, and the contractor likes your design, so all is well. A deal is made to finish the installation of those cabinets in two weeks, complete with the hardware. Great. But then you discover these cool undermount lights that would make your countertops look extra cool, and all that needs to happen is that your contractor must drill holes in the back of each cabinet before

instkitchenallation so that the electrician can wire them seamlessly into your plans. This is a simple task, drilling a hole in each cabinet, and you have not asked the contractor to do any electrical installation whatsoever. But those holes must be measured precisely so that the wiring is exact – which takes time. And math. And a drill.

Scope creep.

Your lights will look great, though.

Your cabinetry will now take one and a half weeks to install. And it might cost a little extra.

How badly do you want those lights?

How much does the customer need that extra functionality in the software?

Now, on to why technical writers care.

Each time I have a project laid out in my Agile Calendar, I have planned a certain number of hours for each project. I know roughly how many hours it will take me to learn and understand a software feature, whether I will understand it based on what the developer hands me or if I will have questions about where it goes in the existing documentation set, whether I need to create hyperlinks, whether I need to talk to the QA team to see if that procedure needs testing, and whether I need to revise what the developer gave me to make the text more reader-friendly. I have to scope out not just whether that doc must be placed in one section of the manuals, but whether it should be cross-referenced, whether it should be noted in “New Features,” “Release Notes,” and so on. Do I make an announcement to customers? Do I have to provide notes in any other sections? The current online documentation that I curate would span over 6,000 pages if printed, so I am mindful not to repeat my writing in too many places, hoping to never have the doc reach 7,000 pages – just in case we ever print it!

This fact – that I have a planned set of hours – means that when a developer (or the team of developers) decides that the cabinets could use some really cool undermount lights, I have to readjust my calendar accordingly. I am, in this metaphor, the electrician who is about to find out that her small rewiring job is about to include 20 new lights to install. My calendar shifts quite a bit! When I start out thinking that I have 2 or three documentation changes with one or two hyperlinks and a sentence in the Release Notes, I wind up with a rewrite or an entirely new page, but should I complain? The customer ends up with cool undermount lights!

Well…scope creepers beware. Technical writers can bring about scope creep on a whole new level. Being mindful of a document’s goal, or a document set’s goal, is a big task. In the planning and execution stages, it is my job to make sure that each of the reader’s needs are addressed. When my team creeps, adding new functionality, I tend to creep even further, trying to make sure that my users get ALL of the information relevant to that new function. See where this is going? The developer adds detail, I add detail. It’s like getting a little crazy with the salt shaker.


So, fellow writers, here is my wisdom to you – do your darndest to work on the examples and the  metaphors and avoid the creep. Stall the creep at its root. Break your chunks into smaller chunks and help your developers and your project managers do the same. It’s totally fine to put in the undermount lights, but remind them that a whole new manual page needs to be written to tell users how to turn the lights on and off, how to operate the dimmer switch, and where the breaker is located.

Express early and often that if they want to add new functionality, they must write a new story. They should ask whether it is really a new feature. They should approach your time and expertise with more than “it’s a minor doc change/update/addition” each time they add a cool bell or whistle – or undermount light.

If the scope must get broader, we must return to the goal and reevaluate. Consider whether those lights are their own entity, or whether they can brighten up the whole room – or whether they will simply cast a creepy glow all over everything when you come to the kitchen for a glass of water in the middle of the night.moon




Risky Business



Risky Business – The pitfalls of users who truly don’t read the doc.

We’ve all been there. The daily task of looking at the comments section of our documentation to respond to users, only to discover a question or comment from a customer only to respond in frustration because he or she clearly did not read the precious words we’ve written. It’s obvious from the question asked, or the comment noted, because we’ve addressed the very issue just lines before, so crisply and clearly, they could not possibly have missed it.

How do we achieve that elusive goal- getting customers to comply? Why, oh why do customers ignore our hard work?

It turns out that customer compliance is a multilayered issue, and there is, as you would expect, no simple answer, but that doesn’t mean that it is out of reach. In order to get at the issue, you have to think of it much like an adventure I had when I was younger, though. Work with me on this:

I grew up in the center of a small town. My parents were professionals. I went away for a couple of weeks each summer to sleepaway camp and spent the bookend weekends with my Aunt Helen who lived on a working farm. When I was about 12 years old, on the first weekend, before camp started, we picked cherries and strawberries, canned some tomatoes, and I fed the chickens who pecked lazily in the field behind her house. I marveled at the acres of corn in tidy rows that would be ripe in a few weeks. I asked her the names of the hens.

“They don’t have names,” she said, “They give eggs a while, and then they’re food.”

So I nhensamed them. Bess, Mavis, Charlotte, Diana, Mary Ann, and so on. There were ten of them. They were cute, and they pecked near my feet. I could tell them apart based on color patterns and wattles. They each had unique personalities, even. I felt they deserved names. They were practically tame, after all.

In a couple of days, Aunt Helen drove me to camp, and I didn’t think much about her or the hens until I returned two weeks later to enjoy a couple more farm days before returning back to my parents and my hometown for the rest of the summer.

The problem was, three of the hens were gone. There were only two left – Charlotte and Bess. I looked for them in the yard, thinking they had hidden in the roost, or gone off to find shade. Of course they hadn’t. When I asked Aunt Helen, she matter-of-factly reminded me that they were food. My uncle John had wrung their necks, plucked them featherless, cut them up and wrapped them for freezing.

My expectations for the chickens and My Aunt Helen’s were vastly different. In other words, people don’t always behave or respond in the ways you expect them to. My Aunt had explained to me why the hens didn’t have names. I just didn’t follow directions very well. Lesson learned, feelings hurt.

Users are the same way, but when they don’t comply, sometimes it’s not just their feelings that are bruised.

There can be risks for the user in that users who fail to read or interpret the documentation fully are at risk of damaging the product (or, often themselves) through misuse or improper installation. And there are risks for their company or business because they will invariably head to the support department, resulting in higher costs, OR, as is the case in the primary example I used here, they will leave a time-consuming question or comment that could have been dodged had they merely read the doc.

So although there are lots of factors that can impact user compliance and reduce these risks, let’s dive into the top three that impact behavior and reduce risk:

Age. I work in mainframe software, so I am keenly aware of age. Usability pros are keenly aware of the link between age and reading patterns, especially when it comes to web-based content. Older users read more, and do not look to leave a page through clicking quite as often. Be aware, though, in design, that older users can miss imbedded links without other visual cues, so placing links below the original field (one page, no scrolling) can be a tricky thing. Think of page design as just that – like a newspaper, things that are placed “below the fold” are often viewed as less important if the target demographic is the 50+ group.

Next up is Education Level. Those with a greater education will stick to a greater focus in reading, where less educated page visitors will skip around looking for the graphic or link that takes them to the next step. This is a tricky design element, because pages get quickly busy, especially when graphics and diagrams are essential to the basic function of what you are trying to convey.

Industry. This is tough because software is different from science which is different from automotive (I could go on and on in the areas of tech doc, and we all know it). This is a terribly important factor, and yet it still ranks behind age and education. We are no longer “reading the manual” in page form, so we have to be slicker than that. But heavily-regulated industries like software and medicine require us to be vigilant in testing and certifying our documentation and also require lots of compliance with the voluminous doc we include. Be choosy in design, and this will help a lot.

What we know about what never works (or mostly doesn’t work)

Plenty of times, designers think that issuing a stern warning to “Read this!” Will make users more aware and thus they will read. That is simply not so. Telling people to read often makes no difference. If users are prepared to comply, they will. If they are planning to skip over or skim, your handy warning is not about to move them along.

Overusing warning signals, notes and other hazard signs does not seem to do the trick, either. UX designers have tried to put the visual equivalent of caution tape along the reader’s path, but to no avail. Even when users will experience a serious outcome like an outage or data loss, very rarely does a warning lead customers to be more wary. (Does this feel like it’s getting grim?)

Overuse of design elements like boxes or offsets also has little effect. Sometimes it is visually stunning, but it does not cause folks to read what is inside, alas.

So what do we do?

There IS hope, dear writer – there are proven methods to perk up your reader and get her to pay attention, I assure you. All is not lost.

The first and simplest is first and it is simple.

Lean doc. Lowest common denominator. Think about how easy it is to read a YA novel. If you haven’t done it, go flip through “The Hunger Games.” It’s not a bad story, seriously. The writing is pretty good. Or try “The Giver.” When writing is clean and written to a simpler audience, it goes by in a breeze. So do that. Give up on verbosity and passivity. Get things moving. Don’t write high; write low.

Layer things to keep it interesting. Ignore part of what I said in the previous paragraph and throw in something seriously challenging every now and then just to spice things up. Don’t complicate matters just for the sake of complication, mind you. And don’t write a 42-word sentence to prove anything to your high school English teacher. Just go ahead and write the processes for grown-ups in a naturally challenging way.

Test your work. Then test it again. Make sure that what you have written works. If you create a trusted setting and climate in your documentation, you will be trusted. Respond quickly and accurately to your clients when they do make those comments that clearly could have been solved by reading the doc and gently redirect their attention to the place in the paragraphs where you explained it. Do a little hand-holding so they can see the benefit of your well-crafted prose. I assure you, building that relationship is worth almost as much as your fine prose. When users can peek behind the curtain to see that the writer is there, pen-in-hand and really knows her stuff, it is like a miracle occurred. And it is a thing of beauty.

That is the moment when, like Tom Cruise in the movie, you can don your sunglasses and dance to whatever music you want – no one is watching and you have the best moves ever.

But unlike the character he plays in that ubiquitous film, your story ends much, much better.



Agility 2.0 – Drive the Doc


In the age of agile, companies and teams all over are integrating new documentation practices as best they can in a more streamlined, cooperative practice environment. Continuous delivery of software or an integrated delivery environment can be a challenge not just for software engineers, but certainly for technical communicators. Hey, it’s hard to write the doc before the software has been written, quality-tested and everyone has had a chance to kick the tires and take the thing out for a drive. But we try. In a perfect agile world, there could be a new feature or function of software release once a day! But can we really write and revise documentation every day? That seems unlikely, and probably unnecessary. We know that our users don’t relish reading the documentation, after all.

It is a practical chorus in my office: “Who reads the doc?”

I argue often that those who read the doc are experiencing a pain point, and that it is my job to ease that pain before it becomes excruciating. They are undergoing the pain of introduction, installation, or – and we hope this is not the case – they’ve hit trouble.

So sometimes, it is indeed true that perhaps the doc should be updated daily, with new screenshots, demos, integrations…who knows? If something changes fast in the world of software, don’t we want the documentation to keep up as well? I definitely do.

There are some great tools in the field to help with automation ottsf doc – At MadWorld, we got to see how Jenkins builds works with MadCap Flare to conduct an automatic publish (that is a dream of mine, believe me). I imagine the day when I can integrate development and documentation, but there are some days when that seems like a far-off dream. Should I be satisfied with just DITA? Of course not.


Having trouble picturing what I mean? Imagine this: I want to automate a document that provides the directions from my office to my home. I could write these directions, “Exit the parking lot by turning left onto Smith Street. At the stop sign, turn right onto Maple Avenue. Pcarmaproceed one-point-three miles to Mary Street. Turn left onto Mary Street,” and so on until I reach my destination. I would have produced an accurate document reflecting the journey from office to home. However, on a sunny Tuesday, I discover that there is construction on Mary Street. The construction will last a week or more, so the directions to my house have changed – at least in the short term. I have to change the document, and I have to change it today. If I could dictate the directions to a VUI as I drive, I could have a new document in moments. In fact, as soon as I pass the construction and reconnect to a spot where the route is the same as the old document, I could stop the modification. I could merge the first document with the new one, republish, and my work would be complete.

That is just one way to automate, but since I am using a model of doc change while driving, I like it! There are of course other models of doc change while developing, but this one is pretty cool. I’m not sure there is a whole lot of need for updated turn-by-turn printed directions, but it was an easy model. Now imagine if I could apply this to updated installation for software, or a new release model for medication or pharmacopeia. I can go on and on about the potential, but if it is “dictate and publish,” it’s game on. If my developers can help talk through the model, I can clean up text with an editor and have my truly agile production line – shazam!

Text-to-speech modeling and agility are at the edge. Automating publishing is there, too. It will be fun to watch the merge points. (Merge, get it?) Get in the car, and let’s see where the construction zones are.

It’s All About AI. The Data Told Me So.

AIA 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.

toiletAccording 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.

Image result for artificial intelligence

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.





Simplifying Complexity

Sometimes when I think about that task – simplifying the complex – it sounds as easy as boiling the ocean. Other times it comes as naturally to me as making toast. (Since I don’t eat toast, or even own a toaster, perhaps I should take that as a sign. It is never easy to make complex things simple. Not even making toast.)

Image result for toast

Yet every day, what I do in my work is to take cumbersome, complex tasks and recreate them in the simplest possible terms. When a huge banking system has millions of transactions per day and must synthesize them into calculable terms…I create language that can handle that. When there is an installation process that takes hundreds of functions that need to be done in seconds, not hours, I write the tasks that do that in ways that humans can understand without advanced degrees. I take complex ideas and distill them for actual people.

Brunch-MimosasMany years ago, when I was a bridesmaid for a dear friend, we hosted a brunch for the bride just a few days before her big day. In sunny Edmond, OK, just outside of Oklahoma City, we gathered around floral arrangements and mimosas for a few final gifts and sentiments. One of the things we had arranged for my dear friend was a book of recipes – not an atypical gift for a young bride. However, she was not your average young homemaker. We knew her so well that the homemade book, a collection to which we had all contributed, was filled with precious advice like “Vegetable Soup: Open can. Pour into saucepan. Do not overheat, boil, or otherwise burn.” And another great one: “Swedish Meatballs: Drive to your local Ikea. Once there, find the café. All will be well.” And perhaps the best: “Breakfast in bed: Open Pop Tarts box. Remove items from foil wrapper. Return to bed. Serves two.”

This gift indeed made the complex simple. It did not, however, lead to a gourmet life for the newlyweds. Nor did it improve her cooking skills. Hopefully she took some cooking classes or they made lots of reservations. No matter, she eventually became a successful oncologist and he a high school biology teacher. No one starved.

chocolate chip

The kitchen is the perfect example of where good writing, clean instructions, are essential to making the complex simple. Baking is an intricate act of chemistry that, if not executed properly, can yield disastrous results. The chemical process involved in baking bread is a dance of molecules that defies the odds of nature, and yet displays the beautiful synergy of both science and art.

On the other hand, missteps in the kitchen can yield fantastic new gifts, too. Who can overlook the great story on any package of Nestle chocolate chips, telling the untrue tale of Ruth Graves Wakefield and her adventures in creating Toll House cookies? (I hate to break it to you, but they were not really a mistake. Ruth was not trying to create chocolate cookies. She meant to keep those little chocolate nuggets intact, after all.)

My point is that every chocolate chip cookie recipe has a slightly different taste based upon a simple change: the recipe. Making the complex recipe ingredients: let’s face it, there are frequently at least TEN ingredients in the cookie recipe – and their variants.

Think about the variants alone:

Salt or no salt (I’ve tried it both ways, to varying result)

The # of eggs can differ

Fat – this is butter vs margarine or shortening. The variations in recipes is astonishing

A leavening agent – typically baking powder, but sometimes baking soda

The amount of flour, also the kind of flour

Whether to cream all of the fats and liquids before adding the sugars

The ratio of fats to flours

The ratio of ingredients and mixing and cooking times

All this is to say that just when you thought a simple task – making a batch of chocolate chip cookies – was just that, a simple task, you forgot that a whole lot of design and consideration went into the planning of that document. Or did it? Probably not. Your mom or her mom wrote down the recipe and you either liked her cookies or you liked someone else’s mom’s cookies. (My daughter prefers her friend Evan’s mom’s cookies to mine, if I am honest. And this is a good thing, because I shun carbohydrates and sugars like they bear the plague upon my house, so I cannot be trusted to bake anyway. I send college care packages of kale chips and they are darn good!) But when mom was perfecting that recipe, writing down all of the tweaks and updates, she was user-testing and updating the technical document. She just didn’t know it.

Even the original plan – the measuring of ingredients and the testing of oven temperature and the execution of the recipe – all of that was fragile and technical and required patience and repetition. The information that first started out on a sheet of paper next to the oven had to be user-tested and rethought once or twice. Or five times. It’s just that no one labeled it “tech writing” before they put it on a recipe card.

So now, all of these years later, while I am plotting out the schema for decoupling a conversational AI documentation scenario, I hope you will bear with me. I think one of the primary questions I will look into this week is, “Alexa, what is the ideal number of chocolate chips to put into a single cookie?” While I am researching the pure voice interactions and trying to nail down the intents and utterances and the minute specifics of how we can integrate this practice into the fiber of our lives, remember, it all started with the desire to simplify – and to make a cookie. So I’ll begin with that question about how many chips.

Once I have that answer, I will report back to you on the salt or no salt question, and then I will move on to the perfect flour ratio, and we’ll move on from there.  Or maybe I will create the ultimate kale chip recipe for a college care package.




What to Do When Your Documentation Speaks… Literally



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.

Allow me.

innovationYou 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.oyster

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.

Please Release Me!


As soon as I thought about writing a post about Release Notes, I got that old Englebert Humperdink song stuck in my head, “Please release me, let me go..” and it’s been stuck in there ever since. When that played on the radio when I was a kid, it was the worst earworm ever! But it has nothing to do with writing a good set of release notes, and it just serves to distract me from the task at hand.

As technical writers, we are tasked with documenting (we hope) multiple releases of successful software products. A vital part of that job is letting customers know what has changed from one release to another, especially when something might alter the way a customer uses the product. Sometimes the change is exciting – like a new feature. Sometimes it’s less glamorous, like the deprecation of code functions.

At their most minimal, release notes are merely called changelogs, and are not full-blown release notes at all. Changelogs are just companions to the documentation that can be sent along periodically and take far less work than the notes that accompany a Generally-Available Release. For a major GA release, you can and should anticipate preparing not just technical notes, but a greater suite of materials that will help your product succeed in the market.

Ahh..but I am just a lowly tech writer, you say. Well, if you choose to remain so, then only prep a section of tech doc that discusses the technical aspects of the release, and there you have it. If you want to view your software as an asset and you’d like to continue writing doc for it and for your company, listen well.

What to Include in Release Notes:

New Features and Functionsnew-sign-ID-33314

Let readers know what new features are packed in to the product, and how those enhance their experiences. The Release Notes section allows for a teensy bit of latitude where you can provide an information-loaded summary of what that feature means and how users can implement it. What does it mean to them? What is the business value? Depending on your business’ practice, you might be able to include a screenshot, an illustration, or a video demo.

If the feature or function came out of ideation, you could link to the community where the request was made, so that customers know that their voices are being heard. They really dig that.

Make sure that New features is the first item in your Release Notes. Don’t let it be overshadowed by anything else, like…

Bug Fixes                                                                                         scared-bug

Listing the bugs that your team has encountered and corrected is important in the upfront Release Notes, but even more important is linking to the documentation where the bug reports and further information resides. It’s no good to just say, “hey we fixed this,” but not to say “here’s where to get that new stuff.” I’ve seen plenty of doc that does the former but not the latter. It’s just a courtesy to point your users directly to the goods.

It is important to note the Bug Fixes, but don’t let them get anyone down. They were glitches, after all, so celebrate the fact that they were Fixed! Go, you! Because next up, you deed to call attention to deprecations.

Deprecations                                                                    Fox

Nobody celebrates these, and yet you have to let users know about the parts and pieces that are just no longer useful. If part of your product is headed out to pasture, you’ve got to say, “sorry, folks, this is being taken off the shelf.” You don’t necessarily have to say why, because hopefully you’ve covered that in sprint reviews and whatnot, but you do have to make sure you place this prominently in your Release Notes, because not everyone attends those review meetings, or knows in advance about such retirements.

On the other hand, don’t dwell. Do let customers know if there is an alternative – like substituting margarine for butter or stevia for sugar, that sort of thing. Absolutely link to a migration guide so that they know how to get the job done moving from one release to another. Don’t leave anyone hanging without the tools they need.

Why did I bother to put this little guide together?

Well, because I have seen some good release notes and I have seen some bad release notes. I troll around in other product documentation; I don’t keep my head in the box at my own company. I find it intriguing to look around at best practices and see what’s going on. I strategize and learn. One of the things I like to do is to put myself in the shoes of my user. If you don’t do that, you are not a good writer. There. I said it. We are not writing fiction here, folks. These are user guides. USER.  So look at things from that vantage point and see if it works. Not only if it works, but if it is easy. Do you enjoy it? I don’t mean if it’s superfun, because no, it is not super fun. Dancing on Saturday night with your besties is super fun, but is it a pleasant experience that you do not hate at 2:00 on a Thursday? Good. Then you wrote some good documentation and that is all we can ask for. Congratulations.

notes (1)

Once you have that all set and in place, jot down a section of “Other Notes.” This is stuff you grab from UX, from your internal SMEs, things that are overlooked and the orphans of the whole set. The “junk drawer,” if you will. Toss it in a section, build something for it. There is a reason that nearly all of us have a junk drawer in our kitchens – we have odds and ends, but they are useful little nuggets. Your Release Notes might have those, too. But before you toss in too much stuff, take a good look at those nuggets and really ask if they don’t belong in one of those other categories. They truly might. A very smart designer friend of mine once told me that stacks of things are really just unmade decisions. She’s right. So don’t stack your stuff, that junk drawer of doc, just because you don’t want to deal with it. Make some decisions. But even that smart designer friend has a junk drawer. It’s just a nearly-empty junk drawer.

And there you have it. Delight your customers with neat, tidy, efficient user-friendly Release Notes, and be on your merry way. Strategy 101.

By the way, I think the real reason I wrote this is because…guess what…I just finished writing, you guessed it…a whole new set of release notes. With a very small junk drawer. Yay, me.

Strategically Named



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.

smart girlI 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 necelightbulbssary 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.


Nice to meet you.



Is it Writing or is it Content?




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 writing-voicepursuing 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.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.

books4People 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.”

Picking up the #Slack

I recently read a post that another tech writer wrote about the great value he got out of attending a conference, and it got me to thinking about whether I missed the academic conferences I used to attend when I was in Higher Education, that conference-heavy publish-or-perish world that used to frame my professional life.

I do rather miss those conferences, but not because they helped in my professional conferencedevelopment at all. I miss them because they were rather fantastic social networking events where I got to visit nifty cities and see old friends, meet new friends and make some cool connections that would become Facebook pals I’d never see again anywhere other than social media. I’d occasionally hear a good lecture, but more often than not I would gain little professionally and more socially from those conferences. Even the ones where I was a presenter. Don’t get me wrong – there is assuredly professional gain. It is a boon to my resume that I gave a talk at The Rhetoric Society of America. That I delivered a conference paper at The Conference on College Composition and Communication when it was in New York City. It’s kind of a big deal. I did my share of networking, it’s true.

But it is also true that when I was at a conference for Professional and Technical Writing programs and a primary speaker was delivering a talk about women in the professions and helping each other through academic networking I sought her out afterward, only to email her and never hear from her again. Talk about deflating. I did, though, enjoy the venue and the cocktail hour and I made a friend there who is totally into mountain biking and lives in Colorado and we are Facebook pals and we swear one of these days we are going to get together and bike in Utah which we both love. We’ll do it, too, I just know it! The experience of making that Facebook friend is obviously the more valuable experience. Totally worth the money I spent on the conference.

In my professional life, I gain much, much more from networking threads like Slack and Google Plus or Google Docs because I get actual work done there. I collaborate on the daily with other professionals who do what I do, who think like I think, and they interact and respond in real time without the hotel bar chit chat and the façade of friendly. I’ve yet to have a Google hangout with my colleagues fail to result in real feedback, but I’ve definitely had conferences end with “sure, I’d love to look at that manuscript,” only to have neither party send a manuscript or even reach out with a professional email. At conferencing events, offers of reach-out are made, but they are sometimes disingenuous. With options like LinkedIn or Slack, the work is in front of you and the gift is made. It’s in print – albeit digital print. It is more difficult to retract if the ask is not made with a glass of pinot noir in one hand. The work is sincere and the response is real. We work hard in this business, or in any business, and time is short, days are long but wide. It is time to put shoulders to the grindstone if we want real results.

New-Orleans-for-desktopDigital is the new real, and though those professional conferences sure are delightful if they are in Vegas or New Orleans or New York, I’d rather get my work done from my Pittsburgh home office and go out to celebrate after the amazing writing hits the screen – like it just did!