Who needs an Editorial Calendar? You, that’s Who.

~ Susan Kelley ~ Leave a comment

For a long time, I thought that content management should be an organic process. That is to say, when something needed to be written or re-written, I’d know it, because the project or task would manifest itself as a feature or project story through my Agile Development calendar or it would emerge through technical debt, and I’d address it. I could do content cleanup and I wouldn’t waste precious hours calendaring. I already spend time providing regular posts and I have a notes app where I jot ideas – I have plenty of them – so I can harvest things. I use Evernote to tack web pages for references to my writing, so for a long time I thought an editorial calendar was superfluous.

But…

When my writing came to more teamwork and content that impacted internal teams as well as tech, well then. Sharing platforms and thinking about notation on spreadsheets? Content planning became a science as much as an art. Into my world came the Editorial Calendar. I thought about what I might want to do in planning, not just on a whim.

An editorial calendar allows me to:

  • Consider a production schedule that is more consistent
  • Track social media
  • Encourage collaboration, not just solo production
  • Balance content for graphics, media, and formatting
  • Be accountable, if only to myself
  • Analyze posts for popularity and relevance
  • Plan things seasonally, well in advance

There are so many resources for calendaring that it can be overwhelming at first, but it’s not too hard to winnow things down quickly. Curata has a sweet graphic of templates and their features.

But I tend to just use Google Sheets. (not my sample)

WordPress also has a Plug-in, but hey…we all find our groove, right?

So what should go in your calendar? Well, that is largely up to you, but the basics are the basics:

How much content – are you super sleek and it’s just a tweet a day? Maybe, but it might be a blog post or even a few articles, a column, maybe a book chapter? Maybe you are looking at weekly, monthly targets.

Personas – definitely scope out your targets

Producers – who writes your stuff, who is responsible for what: copy, editors, will your blogging team in-house handle it or do you outsource some? Do you have a team, or solo folks? Name names.

Frequency of delivery – not frequency of writing, but when does the copy move out the door

Last, be flexy – Remember, there are holidays, people take leave (even you) and stuff might need an edit pass, new research, something changes. There are dates and then there are deadlines. Look, if a date is immovable, put it in bold red. But otherwise, understand that quality is super important. Ideas sometimes get superseded by better ideas.

I recently wrote a memoir. It took more than 2 years. I am still looking for an agent. The book is finished, but no one is publishing it yet. That part is not on my calendar, but the to-do lists surrounding it are. They are not concrete, but pretty close. They are important but not firm. My publishing schedule is important, they are on my editorial calendar just like this post was on my calendar, but I had to look up some stuff.

There were some work dates that were also important that needed addressing before I could do my fact-checking for this, so those went in. But hey, look, this made the site. Cool! And you are reading it (you are, right?) so yay, me.

Go find an app, test it out and kick the tires.

Calendar some dates – put an editorial calendar on your calendar.

Advertisement

Dear Writers, Please Fail to Succeed

~ Susan Kelley ~ Leave a comment

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 measure success.

Allow me to meander a bit. We’ll focus on writing in a moment.

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.

The Data Story

~ Susan Kelley ~ Leave a comment

I’ve mentioned before that I am something of a Data Nerd. This is unusual for someone who is also a “word artist,” but hey, a girl can wear more than one hat, can’t she? I’m also a mother, a triathlete, and a lover of Emily Dickinson’s poetry. In high school, no one would have pegged me as a future triathlete, and no one who knows me now would imagine that I was ever *not* an athlete, so there you have it: the Venn diagram of Susan.

At the heart of this is data. But data about just me is not all that interesting. Data about thousands of people, and especially customers – now that is interesting. Even better is this funky cool tool called “Google Trends.”

As a technical writer and UX Copy Writer, I find this handy-dandy tool super fun and useful. You may be asking why. I’ll tell ya.

With a heavy-lifter of a creation like this, I can sit back and think about trends and numbers in ways I used to have to do lots and lots of work to get at. Research is a UX/UI wonk’s best asset. If I understand what people like, what people do, what people are looking for – I am on top of the world! I can simply and easily take a look at what was, generally, trending in the United States in 2014:

Searches included World Cup, Ebola, Malaysia Airlines, and Flappy Bird. People wanted to know about Kim Novak, and Jared Leto, and the Paleo diet was all the rage. By 2018, folks were clicking to learn about how to apply magnetic lashes. The Paleo diet was gone, but the Keto diet was in. Mega Millions was a top search, along with Logan Paul and Megan Markle.

Peoples’ interests and learning curves mark what I need to know, and they show this in words. Words make their decisions, drive their purchases, and reveal their inner thoughts.

So why is all this information so important? Again, I’ll tell ya.

I like to know which words people choose, and why they choose them. Wouldn’t you like to know why I write this blog, and why I choose the topics I do? I choose the topics because something pops into my head, or creeps its way in after I think about it for a while, and it is something that has been trending, or poking away and needs (in my opinion) to be discussed. It has to do with tech writing, or aspects of technology, women, and writing, and therefore fits the general parameters of this forum. Follow? But then, also it has to interest me. So there is an overlap. That’s where the Venn diagram hits. My interests, crossing over with my expertise, crossing over with something that I think will appeal to YOU.

And then, I write about it. But without the data that I could gather from some nifty tool like Google Trends, where would I be? I’d have no idea that the latest trend, in May of 2019, is that there have been more than 100K searches for Theresa May, and more than 20K of those searches were in Canada. Neat, too, that over 5k Canadian folks searched today (5/24) for the results of the cricket match between Pakistan and Afghanistan, right? Again, why does this matter? Well, because I doubt that any reference in my design documents in the US that refer to cricket would conjure the sport as much as they would reference the insect. And while Theresa May is the top search in Canada, the movie “Aladdin” is the top search in the US, so that tells us a bit about what Americans are thinking this weekend, doesn’t it?

To tie this all back to data and words, I’ll keep it simple. The more we know about users, the more we know. This data isn’t spying, and it isn’t creepy. It is downright useful. As a UX designer and writer, as a technical writer, and as a strong customer advocate, it really, truly, sincerely is all information-based. Lots of times, people in my orbit who are not in the tech realm get a little freaked out about all of this information gathering. But I don’t. I like it a whole lot when I can use data – information – numbers – WORDS – to get me where I am going and get me what I need a lot faster.

Even better when I can deliver that to my users.

Namaste.

Making Meaning

~ Susan Kelley ~ Leave a comment

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 ninth graders.

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

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, so-to-speak.

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, but meaning.

Let’s Talk About Creativity

~ Susan Kelley ~ Leave a comment

 

It is an almost universal refrain

when I tell someone that I am a “Technical Writer for a Software Company.”

“Oh, so not exactly exciting work, huh?”

“That would bore me to tears.”

“I couldn’t stand that kind of mundane work.”

To which I roll my eyes with boredom. Come up with something better, people. Do you really think I voluntarily spend my days sweeping cobwebs from my brain? Do you think it is fair game to insult my vocation simply because you are not bright enough to comprehend what I do?

Apparently, yes.

I’ll correct the record. What I do, while at times highly technical, is also quite creative and enjoyable. And highly technical does not cancel out creative and enjoyable, by the way. I spend my days problem solving and inventing solutions to problems that make users’ lives easier, that attack pain points and smooth out issues. It’s pretty cool.

But I get it. If you are not the sort of person who smiles when reading about coding syntax, then working in software documentation seems drab. (The funny thing is, a technical writer is a veritable savior when you can’t figure out how to install your new printer or why the WiFi isn’t working, amirite?)

The truth is, many of us could benefit from greater creativity in the workplace, not just those of us in technical fields. Most of us thrive if given some measure of creativity, even those who do not define themselves as ‘creatives.’ (Just for the record, I do, in fact, label myself as a creative person, and find outlets for just those tendencies both at work and in my personal life. I recommend it!)

Companies who hope to get the most innovative ideas from their workforce are wise to consider ways to encourage creative productivity in the office. I’ve got a few ideas I’d like to share. We use these on my team, and if you try some (or all – go for it) let me know what works, and add a few more to the tab.

  1. Support risk-taking. Cultivate a culture where risk-taking is just fine. I’m not talking about dangerous risks, but rather innovation risks. Try out a new project, allow for innovation time. At my company, we have periodic “innovation sprints” and “hackathons” to encourage new ideas and projects. Some of the fruit of these sessions have proven wildly successful, and some…have not. The best part is that both results are okay.
  2. Offer flexibility in how to do the work. A really cool thing is when you let your workforce test out ways to do things. While Sharon might do everything by the book and find that to be a super-effective way to get to the finish line, Roger might discover a nifty way to hack that project and the next thing you know, not following protocol will become the new protocol because Roger can show that the new way is a great way. Part of this can be offering a better work-life balance, like maybe Roger really can work better at 5AM than 9AM, and he is super productive then, so in-office time is not a priority, or perhaps Roger is really great at coming up with ideas that he jots down in a notebook first, even though typical company policy is to use only email. Get Roger an Evernote smart notebook, and you are on your way to big ideas!
  3. Think about communal space for idea sharing, even if it is offsite. Recently, my team of tech writers and I learned that our local coffee shop was hosting a 3PM “happy hour” and we decided to take a team meeting at that shop. Best. Idea. Ever. We met for an hour over hot java and solved some documentation issues that we’d not been able to solve at our own desks just by moving our thinking to a new location for an hour. And as a bonus, we all had some delicious coffee and a location break! It isn’t always necessary to move spots, and this time the company didn’t even pay for our meeting. We just had to jog our brains a little bit.
  4. Have fun. It is difficult sometimes to forge a genuine camaraderie, but it is also necessary. Break down silos and make an effort to not just be colleagues, but to be collegial. Creating a convivial mood by generating laughter, enjoying the office, and promoting a fun space generates creativity. Spin up a slack channel where everyone can post pictures of their pets, and pets only. If someone on the team doesn’t have a pet, find a workaround, like an animated pet – (come on, this is a creativity post!) Let inspiration flow freely in channels of communication.
  5. Focus on moving the ball forward in a way that everyone will succeed. Look, I work in technical communication and still the thing I want most is to be successful while I enjoy my work. Understanding that success might not always be money, but might be getting out of the office to enjoy sunshine at lunch time, or it might be the trust to work on a new project, or it might be an office space with better light – any of these are indeed ways to foster my creativity and make my workplace more enjoyable and my work product higher-level.

What’s the upshot of that for my company?

Happier customers, greater return on that investment, better work and for them – a bigger bottom line.

I don’t try very hard to correct people who think my job is boring and don’t understand it. I merely tell them, “Actually, technical writing is pretty cool. Your debit card works because I understand the code behind it and write the installation manual, so I bet you are pretty glad I do my job, right?”

They typically shrug and laugh, which is good enough for me. Little do they know, I have a lot of fun thinking of synonyms for a good part of the day, I create animated installation videos, I write VUI, and I spend a good deal of time daydreaming about the best, most innovative ways to make life easy. All because creativity in the workplace is important to me – so let me know if you can make it important in your tech writing space, too.

 

Simplicity Is Not Just for Sewing Patterns

~ Susan Kelley ~ Leave a comment

 

There used to be job security in system complexity. Now, if you are the person who can simplify the system, you are queen of the world. Today, information flows faster and faster, and it needs to.

math   I recall when my third-grade math teacher told us all, “You won’t always have a calculator at your fingertips, so you will need to learn how to figure out percentages in your head.” Oh, she was a sweetie, that Miss Thompson, but I whip out my iPhone to figure out the tip at the restaurant every single time. And when I am shopping and it’s 30% off? You better believe, I reach in my pocket. So the simplifier rules the game.

It used to be that if the system was complex, it needed repairing, and that kept the repair team in a job. Remember the commercials for that poor, sad, bored Maytag guy? The ones sold a lot of washers and dryers based on reliability alone? In a faster-moving tech world, simply apply that principle to simplicity. No one wants to head to the manual, or call support. As the old saying goes, “Keep it simple, stupid.”

What does this mean, exactly?

The lines are blurring between content and structure, for one thing. The softening of the structured boundary between text, video, and image is an important distinction. Immediately, “manuals” are not “manuals” and reference guides online must seamlessly integrate video with rapid download times so that users can see a diagram followed by a 30-second to one-minute video showing a process, installation or example of how to use the tool or software. The days of scrolling down or clicking into a new window should go the way of the dinosaur. Our new design process should embrace the idea that a caption is not even necessary. Users can come on the journey with us, if we incorporate the right UX design principles into the mix.

The next step we have to embrace is a confluence between social media, mobile capture, and the cloud. Even in high-security systems, we are cloud banking, handling millions of transactions per minute on our phones, keeping virtual wallets, and more. Opening and closing our locks and homes with our keyless entry and embracing IOT. Our documentation systems can do the same thing just as seamlessly if we integrate social media quickly and we are smart. Why any lag time?

The coin we should be trading in now is simplicity, not complexity. To make these systems complex will leave us standing by the

coin

side of the road, waiting for the bus, while the hyperloop passes by above us. The best and most effective CMS systems will be those that rapidly and transparently create single-source doc that makes use of some old-school cut and pasting, but brings it into digital asset management with rapid integration. So, whatever you do when you think about brining your doc into the new era, don’t listen to the tech dev guys who lean toward complex systems because their jobs have always depended upon it. Instead, lean forward to the intuitive systems folks and the cloud-dev UX designers. We are building better mousetraps. The kind that don’t reinvent the wheel in order to ensure that more wheels need to be built.

After all, I do indeed have that calculator in my pocket, Miss Thompson. I didn’t need to learn how to figure percentages. I just needed to embrace the technology 30- years ahead of us.

bus

 

 

Strong Tech Writing is Strong Design Thinking

~ Susan Kelley ~ Leave a comment

I’ve written and talked before about the deep connection I see between UX (User Experience) and ID (Information Development) and yet sometimes I feel like the hamster in the ball, just running around for my own amusement while processes and concepts remain more or less the same.

hamster-ball-1 (1)

I get it, it’s hard to steer large organizations through what seems like a largely creative change with little ROI. And yet I see the returns as potentially huge. As technical writers, when we see the end user as our audience, we know that our writing improves dramatically – that is, when we don’t just see the end user as “installer” or “programmer,” but as “reader of this paragraph or chapter.”

When we think more about audience as consumer-user, we employ real design thinking. That is the moment we become UX-ers supreme. In “The Sciences of the Artificial,” Herbert Simon (insert humble-brag here about how I went to Carnegie Mellon and Simon had a profound career at my alma-mater), charted the first examples of design thinking. Those ideas persuade my processes today, and should inform yours.

First, define – define what you need to resolve, and for what audience. (See how the audience is included there?) You cannot resolve a problem for every audience in the same way, after all.

Second, research Examine the history of the problem at hand. What are the obstacles that prevented it from being solved already? Collect examples of prior solution attempts. Take note of supporters, critics, stakeholders. Talk to the end-users and gather their ideas. Then examine the industry so you can consider other thought leaders’ stances. The solution might be an amalgam that is in plain view.

Next, ideate. Once you know the needs of your users and their motivations, you can generate lots of ideas, and be sure not to judge any of them as frivolous or out-of-bounds. One conversation at a time, you can surface up solutions that are worth exploring.

After this, it’s time to prototype and expand on the ideas and begin to create drafts.

  • – does it sound like I’m talking more about design than text? Take a look back. All of these ideas can be laid out not just in text. Information, after all, might need to be distributed in visuals, charts, video, Voice-User-Interface, graphics… Keep talking with your team about deliverables. After all, someone decided that a Red Octagon was the best delivery mode for a STOP sign, right?

The fifth step is to Choose among the ideas you have and review your objective. Winnowing down ideas by removing both emotion and ownership of ideas is extremely difficult, but once you do it, the next parts are a breeze. Assure team members that there is room for growth all around, and that there is never a penalty for a tossed-out idea, but there is plenty of reward for work on an adopted idea – if we execute a great development, then it is a win-win-win.

At the sixth phase, implement! Create task descriptions if things need to be divided – chunking information or designing graphics, interfaces, scripting or video – that sort of thing. Now is the time to own tasks and divvy up the work. Execute on the best skills and ways of delivering. Then deliver.

The final, seventh part of Simon’s Design Thinking is to Learn. Get feedback from customers, determine if the original goals were met, discuss what could go better nest time, how to improve on the process, measure success, and collect that data so that the next round is better, smoother, and a premium experience.

There is simply no reason not to apply each of these to information development, and the transitions are seamless:

In a nutshell-

  • Audience
  • Research to understand
  • Brainstorm within boundaries
  • Create prototypes that are not limited to textual surfaces
  • Make good choices
  • Implement – execute on your work
  • Execute by strength
  • Learn!

And that, my friends, is Information Design that brings the greatest ROI – no more hamsters.

 

Back Off, Creep!

~ Susan Kelley ~ Leave a comment

 

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.

salt

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

~ Susan Kelley ~ Leave a comment

 

wayfarers

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

~ Susan Kelley ~ Leave a comment

 

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.