Strong Tech Writing is Strong Design Thinking

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!


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