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.)
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.
Many 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.
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.
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.
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.
ssary 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.
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.
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.”
development 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 
Digital 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!
ding and loyalty is perhaps what is at the very epicenter of good internal messaging. When a company is trying out a new path, forging new avenues into new markets, a straightforward, clear internal communications plan is essential. Knowing
perceived to be a non-transparent business communication system, and a poor employee motivational approach. While it is not strictly a communication practice and is more closely related to HR, the rollout in Yahoo’s case was greeted with a great deal of pushback on Yahoo’s own communication message boards. It was met with deafening silence from Yahoo’s CEO, Melissa Mayer. The response is the internal communication failure. The non-collaborative practice practically urges people to stop working together. When expectations are unclear and competition is the goal, people almost always underperform.
ese days, trust is hard to keep. It is easy for a slide deck to appear in New York, and for those employees to tweet the content of that deck to their colleagues in LA to let the cat out of the bag before the presentation is even complete. We must be trustworthy in all our messaging. This means that those of us who are preparing internal messaging must be certain that we are on point long before the cow leaves
Clear and consistent jargon-free messaging has to become part of the company culture. If we can’t get past all of the marketing pizzazz, which is necessary, and the emotional protection, which is also necessary, then we weaken the relationship that we strive to build. 
Women who are encouraged to be leaders have to internalize that role and believe that they can be that role. Leadership is an identity, not just a title. Part of what stymies women in escalating toward these roles is the “human tendency to gravitate to people like oneself,” in which case women are lacking in examples of other powerful women (Ibarra, 2013).
which then assumes the “trailing spouse” (wife) who can pack up and move along with the new job offer. A wife who has no career can easily pack up with the kids and relocate with little trouble to follow the new promotion opportunity. This work-value is much more difficult if the “trailing spouse” is a man with a career trajectory similar to that of his wife.
In Agile Software Development,
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.
Have a Pint at the Tech Pub 