Messaging from the Inside Out


The most important messaging of all might not be advertising, tweeting, or all those posts on LinkedIn. Sometimes, it’s the internal message that rings loudest and clearest.

Why? Because that is the message that carries far past social media and proves that a company is worth working for, and sticking with. A clear internal message increases productivity, which increases growth, and we all know what happens next.

According to Karen Johnson of, effective internal communication “is particularly critical during tumultuous times for an organization to ease anxieties, boost morale and inhibit inaccurate information.” If employees know that their company has a solid plan in place, that eases tensions across the spectrum. But even if the staff knows and recognizes that the company is on unsure footing, if that is communicated well – and openly – they know they can trust upper management and will follow as a team.

Team-builnewpathding 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
that while some areas of the business are under reconstruction, others are steady and moving along as predictable honesty and thoroughness is as important as it gets. What I mean to say here is that especially in a large company, if change is afoot, it is essential to let staff know in the most assuring ways possible that rollouts are going well (when they are going well) because the rumor mill is stronger than any tweet, LinkedIn post or slide deck. Employees will fill in the blanks with conjecture, so it’s far better to have a strong team approach, even when the future is unclear. A well-crafted message can often be the steadiest hand in the entire organization.

Let’s not forget what was perhaps Yahoo’s greatest stumble. Just when they could have been focusing on long or short-term development goals, they decided to pivot toward using Microsoft’s failed QPR (Quarterly Performance Review) system, whereby team members were stack-ranked.

This created an interior bias sentiment, rather than a feeling of open communication system-wide. Stack-ranking is generallyteam-rocks 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.

If the internal messaging is strong, employees feel connected to their company and feel confident in the direction it is taking. This, in turn, creates a connective tissue which bonds the team together, and creates a greater return on the productivity of the team. With strong communication, a company is without a doubt greater than the sum of its parts. The tensile strength can be tested and measured in terms of its output.

This begs the question, then, how do we get internal communication right instead of wrong?

I have some ideas about this. (You probably guessed that , or I would not be blogging on the topic!)

First, connect actions and words. We have tons of jargon in every professional field, and we say that some things are important, but we must follow through. We only develop trust if the actions follow the words. If a promise is made in a document, it must be adhered to in action.

Th100ese 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
the barn. No guessing, no conjecture, no half-baked plans. We owe it to our colleagues to be sure before we print, upload or speak. If we cannot be 100% certain, we must be 100% open about that as well. We must be willing to say, broadly and loudly, that whatever plans we have in place are conjecture. Or else we should not be publicizing those plans.

As communicators, we must be willing and ready to work with managers to build daily, intimate relationships with leadership and staff alike, not sheltering ourselves from both customers and idea-makers in order to understand the whole ball of wax. Internal communicators have a great view, from the top, from the bottom and from the middle. What a great opportunity to see the inner workings of a company, and what great trust is bestowed on the messengers, eh? A vision like no other. But if a communicator is unwilling to see that the message can be transparent but not translucent, then we have done a bad job of being what the company – and the staff needs us to be.

plainlanguageClear 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. Erwin Steinberg, the ubiquitous professor of Professional Writing at Carnegie Mellon University captained “plain language” writing in the professional sphere. That is precisely what is called for here. If we can master that, we will all have done our growing companies the best service of all.

All of these together – simplification in communication, building trust between leadership and staff through openness and idea-sharing, and delivering clear, consistent content in internal communication without the outdated and misguided notion that employees should be somehow shielded or separated from the plan – this is what forward-thinking corporate communications is about. I’m not saying that any company today, especially a large-scale one, should be completely revelatory to the entire workforce. That would be risky and unnecessary. What I mean is that a new level of transparency begets a new level of loyalty, trust, and productivity. We expect our teams today to be agile, responsive, and to deliver not just products but ideas in rapid turnaround. We ask for nearly unprecedented levels of buy-in and conceptual trust at the development level as we test methods of agile release trains and try to get to market faster, better, and leaner than ever before.

If organizations, in turn, create messaging at a similar level of speed, engagement, and positivity, the sky’s the limit in terms of engagement and trust. A facile win for all. Indeed, the communication will flow from the inside out – a great investment.


Shifting Seats

November is that time of year when I am involved in a fantastic event in Pittsburgh called Red Chair.


It is not a Pittsburgh-only event; it’s an event held in many locations around the country for women in technical fields, STEM fields, and it should be much more active than it is, but it’s a grassroots thing, and it’s taking hold. It takes time to build, it takes momentum and it takes money and dedication, but it’ll get there. The idea is big, and hopefully it will grow. But we struggle. The question is, why ?

There are plenty of smart women, talented women, out there, and the numbers of us are growing, and we are not as timid as we were a generation ago, so that’s all good news. But according to a 2016 survey of 263 tech firms, 18% of those companies said their offices were 25% or less female, and 2% had no women at all ( 2016). Perhaps of the greatest concern in all this is that, according to Fortune Magazine, although “the majority of tech execs in London realize that their firms don’t have a diverse workforce…a full 46% of them don’t think increasing diversity would improve their company’s growth” (Fortune, 2016).

There have been plenty of articles written about this, and lots of research in the field, and yet we still lag behind. I’m no expert, but that won’t prevent me from trying one more time (one hundred more times) from weighing in, from passing along the knowledge of others to try to keep the conversation going. Because keeping the conversation going is the crux of the movement, ladies.

A September, 2013 piece in the Harvard Business Review noted that many CEO’s make gender diversity a priority, choosing to insist on placing women in top positions, trying to guide women to senior positions. That was three years ago, so you would think we’d have seen some results, right? Well, part of the problem with those leaders’ approaches, we’ve found, is that they “don’t address the often fragile process of coming to see oneself, and to be seen by others, as a leader” (Ibarra, 2013). There is a tendency to inadvertently undermine a woman’s trajectory toward leadership when advising her to actively seek a role for which she feels mismatched. According to that same article, “the context must support a woman’s motivation to lead and also increase the likelihood that others will recognize and encourage her efforts.” What this means is that the surrounding employees have to see her as a leader, too. That is not always the case.

how-women-leadWomen 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).

The Red Chair event is not just about women in technology, or I wouldn’t have written the last two paragraphs about leadership. Women leaders encourage growth in female staffers. Perhaps they do so no better than their male colleagues, but perhaps they do. The jury’s out, because we lack a breadth of examples, it would seem.

The problem is “that business execs still don’t understand the benefits of having a diverse workforce” (Fortune, 2016). Many organizational structures are, quite simply, designed to fit the lives of men more than they are the lives of women. Consider it – climbing up the career ladder sometimes assumes mobility of place, leadershipwhich 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.

These practices did not set out to stifle women, but nevertheless they do. Women tend to steer clear of jobs, opportunities, and even promotions that might require those types of challenges. We even steer clear of those lines of work completely. And gender-biased hiring managers who do not intend to be gender-biased may consider whether a woman will have the mobility or willingness to pursue the opportunities that a job could offer, both in hiring and promotion.

It’s not so clear, and yet it’s all too apparent.

The weird offshoot of this is that the women who DO succeed end up being the exceptions, not the rule.

At Red Chair, I was surrounded by women who moved across the country, their husbands either followed or they had no husbands. They were either supported or they were alone. Either way, they were touted as exceptional. Why not the norm? There were successful men there who were just…successful. There were women who had “executive presence,” as though this was a characteristic that is unusual. Why so? Many of the men stood tall in their business suits, commanding a certain executive presence merely by being in the room, holding a beer.

Fortunately, the keynote speaker, Lenore Blum,truly is a remarkable woman who deserves to be set apart from the rest. Her accomplishments in the field of mathematics are noteworthy by any standard. She teaches at my alma mater and I admire her work on many levels in the technological field. Many women could look to her and be in awe.

But all of the women in the room were successful, and we need to pull many others in to the room with us, every day, day in and day out, to sit with us in the red chairs, technological and otherwise. We must show our male colleagues and our female colleagues that careers from technical writing to product development are as open to us as anyone, and that our presence in the field improves the field overall. That second-generation bias is present, and unfortunate, but present.

Consider which person in your sphere could use a hand. See if you are the hand she needs.




Refiguring The Primary Measure of Progress

pencilIn Agile Software Development,

“working software is the primary measure of progress” and the manifesto values “working software over comprehensive documentation.”  That is all well and good, but as a writer, I often pause on that one word – comprehensive. I take a moment there and wonder who determines what comprehensive means, and whether sometimes we leave the customer, and the customer’s needs, in the dust when we use that word.


Before every developer everywhere has a head explosion, I think we can all agree that expansive documentation is silly and frivolous. So maybe I would swap out comprehensive for expansive. Perhaps I’d have chosen “frivolous documentation,” or “needless documentation.” I’m just not sure I would have chosen the word comprehensive. I get what the manifesto is going for. I do. I want to create lean, usable doc every time. I don’t want to give more than is needed. I want to respond to change fast. My goal is accurate, deliverable doc that addresses stakeholder needs. I suppose I would like to think that, by definition then, my doc is complete, or…comprehensive…in that it includes everything a customer needs. But I agree that I don’t want it to include anything more. I just want to avoid coming up short.

What if I rewrote the twelve principles from a doc-centric focus? Would they work just as well?

  1. My highest priority is to satisfy the customer through early and continuous delivery of valuable documentation.
  2. Welcome changing requirements, even late in documentation. Agile processes harness edits for the customer’s competitive advantage.
  3. Deliver accurate documentation frequently, from a couple of weeks to a couple of months, with a preference for the shorter timescale.
  4. Business people, developers, and writers must work together daily throughout the project.
  5. Write documentation around motivated individuals. Give them the environment and support they need and trust them to get the doc written.
  6. The most efficient and effective method of conveying information to and within a writing team is face-to-face conversation.
  7. Clear, concise documentation is the primary measure of progress.
  8. Agile processes promote sustainable writing. All team members should be able to maintain a constant pace indefinitely.
  9. Continuous attention to linguistic excellence and good design enhances agility.
  10. Simplicity – the art of maximizing the amount of writing not done or words not written – is essential.
  11. The best architectures, sites, and manuals emerge from self-organizing teams.
  12. At regular intervals, the team reflects on how to create more effective doc and then adjusts accordingly.

Okay, so some of this is silly, and I just wasted twelve lines by playing it out all the way to the end, but it was for good reason. Continuous deployment can happen not just with techmanualdeveloping software, but in the embracing of documentation as part of that software, but instead it is often “kicked to the curb” by many teams as a misinterpretation of that one element of the original manifesto.



It’s not that documentation should be cast aside; it’s that comprehensive documentation is being misunderstood as frivolous or extraneous documentation.

I did not realize that this was a pernicious issue quite so much until I was giving a workshop to a small class of new developers from across my company, hailing from a variety of offices, and they looked at me funny when I described some of how my team does doc (we are pretty good at the whole agile thing, but sometimes we regress into “mini-waterfalls” and I hate them). One of the young devs was astonished that I manage to get my developers to hand over documentation early in the process so that I have it in a draft state, while the code is still being written, not after the code is all in place. It’s a struggle, I’ll admit, but when I this happens, the result is a joyous celebration of shared workload and well-written doc. We can collaborate, change, shift and learn. And the sprint goes more smoothly with only minor changes at the end, not a doc dump in week 4.

To teams who are not doing this: cut it out with the waterfall, guys. Doc is essential, and your users need it. Otherwise, they are calling support and costing your company thousands with every call. Change your practice and build your doc while you build your product.

You might be asking, “How can you possibly write the doc when you haven’t written the code?”

You are not the first person to ask this, trust me. The answer is pretty simple. A long, long time ago, you couldn’t. Or, at least it wasn’t wise to, because it was a redoubling of work. When writers put their stuff into pdfs or word documents, and then had to make major changes, it meant a bunch of editing and rewriting things. Therefore, developers got in the habit of writing all of the code, then examining the processes and hunkering down to crank out the doc. Fair enough. Now, though, we developed wiki spaces and collaborative tech writing tools that now allow inline editing and let developers look at the cool formatting and linking that tech writers have done with our work.

And – before the code even gets written, there is a design plan in place, and usually a design document to go with it. There are code specifications, right? You can have a nice chat with your friendly tech writer and go over this, either through a face-to-face (see Agile point #6) or via any of the vast number of other tools designed to communicate with your team. Before a developer starts coding, there is a project plan – share that plan. Once the general information has stabilized, it’s okay to let the writer have at it. The benefit is that the writer is having her way with the general plan while the developer is coding away. At the end of both work days, the writer and developer have each created something. In a typically short iteration, it is unlikely that the coding will change significantly, so the two can touch base frequently to mark changes (See Agile point #4).

Are there risks to this process? Of course, just like there are with waterfall. Remember that with waterfall, there were a fair amount of times that programming crept right up to the deadline and documentation was hastily delivered and could therefore be sloppy and lacking. And in this method, it is far easier to tell you about writing documentation continuously than it is to actually do it. It takes time, it takes effort, and it takes dedication – because the primary risk for doc is the same as it is for the software: that the customer’s need will change midstream. That problem was (more or less) solved by short iterations in development, and it is (more or less) solved the same way in documentation.mario

The benefit is this – by writing the doc alongside the development, you can be sure that you deliver the doc in sync with the product. You’ll never sent the product out the door with insufficient instruction, and you will never cost your company thousands of dollars in support calls because your customers don’t understand how the product works or how to migrate it. But deliver a product without comprehensive – yes, I’m back to that word – deliver it without a complete doc set, and you may regret it. Trial and error is okay if you want to see how fast Mario can get his Kart down the hill in order to beat Luigi and save the princess, but do you really want to rely on that when the client is a multi-million dollar bank?

I’ve been teaching writing and writing processes for a very long time, and believe me, the action of draft, revise, revise, revise is not new.

It’s just Agile.


Future Content…I’m Content



The buzzword I keep coming across lately (and I am not a fan of buzzwords) is “future content.”


But I have to admit, this one sticks with me because it’s not an industry-generated term that is used to sell stuff or a new word packaging an old idea this time. I keep stumbling across this term, I think, because those who are savvy in the industry are (finally?) grasping the notion that we are writing not for the now, or for the past, like we once were, but we are truly writing to an audience that is ahead of us, and that our writing will span media and must address that. I mean MUST address that.

Future content is not a particularly new idea, though. It’s not like this emerged on the stage in 2016 and I am revealing something that you should congratulate me for. No, sadly, I am not that innovative. It’s just that the idea is sticking with me right now because I am thinking a lot about content strategy and where it will lead me. In my own work, for example, I am poking a lot around in a project that quantifies writers’ work and evaluates and measures product and rule-adherence while at the same time examining SEO, incoming links, and a few other metrics that are of varying levels of importance to a range of stakeholders.

In some ways this aligns with, and in some ways this competes with, my interpretation of real content strategy. My understanding of what I need to do to build great content is this:

  • Customer research
  • Competitor research
  • Company research

…and likely in that order

So I’m talking Content Strategy. But how do we define content strategy with an eye toward future preservation? Way back in 2009, Daniel Jacobson, who is now the VP of something called Edge Engineering at Netflix, wrote a guest post for NPR since he was then the Director of Application Development there.  Jacobson’s post is a great look at a concept called COPE – Create Once, Publish Everywhere, and it’s a great concept that definitely tunes into future content because who wants to work three, four, five times as hard to cover all platforms accessed by the customer, and yet we are responsible to all of those platforms. Jacobson points out a well-designed pipeline from the Data Entry Layer to the Presentation Layer where at the data entry layer there are people and automated functions, but at the output, or presentation layer, there are six different outputs, with presenters ranging from NPR to station modules, all pushing content to users in an array of settings. According to Jacobson, COPE is a philosophy that encompasses areas of content management systems (CMS), a way of thinking about content more broadly. It is important, then, to think of content as fitting within a whole distribution system. Jacobson was keen to distinguish COPE from a Web-publishing tool, even in 2009. (This explains why he is now at Netflix, folks.)slick-tablet

Looking back to 2009 does not detract from looking to the future. Navigation that leads from data entry to presentation and results in well-organized content that users can access from a laptop, a phone, a tablet, or whichever device they happen to find useful at the moment – that is future content. Content that is driven by text, video, sound, some combination of all three, or a weaving of two or an overlap – that is future content. Linking in media when it is needed, and knowing when it is not – that is future content.  It’s useful, accessible, usable, understandable, customer-driven, and attractive. (I saved the best for last there.)antique-book-18

If it looks good, feels good, is easy to find and use – it’s future content. Now isn’t it odd that it seems to me that with each new concept in writing: the sheaf of paper, the bound book, the glossy magazine, the e-book, the slick tablet, the iBook and whatever comes next…each one is future content? The thing that makes it valuable is whether it is well-written, understandable and worth reading? What makes it worthwhile is whether or not it is worth my time? Does the content deliver against objective? Does it stand out among all the other content?

So I truly need to go back to determining if someone has done his or her:

  • Customer research
  • Competitor research
  • Company research

Right? And that is content management. For the future.

A User Experience View


One of the roadblocks Technical Writers experience quite often, especially in software documentation, is overcoming obstacles in the usability of our doc. In a fast-paced environment like software development, staying ahead of the curve is important, of course. There is always a new program or product to help us write our doc. But will our company invest in it? Is it worth the cost? It’s expensive to train teams on the technology, right? And integrating those new features into existing documentation is not seamless. Competing programs don’t typically work seamlessly with each other. I just read a post about the most valuable tools to tech writers, and while many agreed that Madcap Flare is the tool du jour, that came as no surprise, since a handful of the writers referenced in the article work at MadCap. Other tools noted included Camtasia, Adobe products and even my personal nemesis, Acrolinx  (In a later post, I’ll explain why I am not an Acrolinx fan, but let’s save that for another day.)

While the tools we have at our fingertips certainly have a great impact on the work we are able to produce, we as writers can lean on those tools too greatly if we overlook the simplest of design elements and forsake the foundation of what our documentation must be in the first place: usable.

We know that Technical Documentation has a utilitarian function. It has a use purpose: it meets a need of the user because the user requires documentation to, say, install a product. So we have already jumped the first hurdle of the UX measure by designing something that fills a customer need. Check that off the list.

The second hurdle is Usability. We must jump this hurdle by creating something that is easy. In a UX model, we are tasked with creating something that can be navigated with ease. This is where our tools come in handy (or not). If our customers cannot use our documentation easily, we have not cleared this hurdle. Think of the handheld electronics that come packaged with the foldout instructions in print so small that one needs a magnifying glass to decipher even the battery installation. Do we really want to continue that trend? Of course not. Creating easily-used documentation is key.

The next area is Desirablility. Normally, in the past no one thought of technical writing, least of all something like software documentation, as having a desirability factor. Well…I’ve spent a good bit of time creating some YouTube videos that are not necessarily going to win any MTV awards, but they are not exactly difficult to watch. If my customers desire the video over the lengthy text, so be it. This is why a tool like Camtasia or Captivate9 is my favorite tool today.

If my customers feel no pain in clicking through the doc I’ve created because the experience is smoother than tabbing a PDF, it’s a win. In today’s field filled with rich media, documentation is often more off the page than on. Creating pleasing ways of reaching customers with information is an essential piece of the puzzle. So, if I can set up something for a customer whose reaction is more or less, “I like the way this looks,” or “I’ve had a satisfying experience,” then my goal is achieved. It’s why I often marvel when any company is reluctant to jump on board when a technical writer shows management the latest tool toward potential great documentation. (If any of you in management anywhere are listening – equip your writers with the stuff they need to get truly creative. You are unlikely to regret the monetary investment in truly slick presentations, but you are very likely to regret being late to the game. I’m just sayin’.)

Last on the list is to create an overall satisfying Brand Experience. When the other hurdles have been cleared – and generally only when the other hurdles have been cleared – the Brand Experience can be a positive one, because the Utility (need), Usability (ease of access), Desirability (want or perceived want) have been met, and they lead to loyalty. According to J. Josko Braus, of the University of Rochester, brand experience is primarily a sensation or a feeling, but it is part of a brand’s “identity, packaging, communications and environments.”

Braus points out that when customers first engage with a product, they are engaged with its “utilitarian product attributes,” so in this case, my customers are engaged with product documentation (after all, as a technical writer, I’m really selling my doc, but on behalf of the product at large. My customers will associate that documentation with my company’s name, logo, and more, but only on a broader scale. I can hope that customers will be delighted with the overall experience of the end-product, but only after they are satisfied with the Brand Experience they’ve had with my doc.

I could get all academic here, and take you down the rabbit-hole into the debate surrounding Brand Experience, but my focus is on User Experience and how it centers in documentation. If Usability is all about being able to use something, then the User experience differs here because I want my users to be able to have a good feeling about using my documentation – to experience it in a way that enhances their overall engagement with the documentation.

Think of it this way: a usable stapler is one that performs the task. It staples papers together.

Ugly stapler

And yet when you have mastered the hurdle of mere utility, you can also move ahead with usability, desirability, and brand experience. Because who wouldn’t prefer a really good-looking stapler?

Building a Better Mousetrap, or Better Mousetrap Documentation Anyway



In the days of Waterfall Software Development, nobody wanted to pay much attention to Doc Development. I mean, let’s be honest. It was the second-to-last step in the whole process, and pretty much the least glamorous. Although documentation had the potential to occur at any point in the product life cycle, as we have proven with Agile methodology, everyone saved it until near the end, believing it had to be placed until after all of the development, coding and testing was complete, but until before packaging was ready.

We now know that Doc is part of the system, an integral one at that, and yet sometimes it is still the redhead in the room, not getting its due unless it steps up with its fiery temper, begging for the attention it deserves. We know that in some very successful organizations, Documentation gets a well-earned 20-40% of total development effort, while in other organizations, it falls by the wayside, and that lack of effort shows. A perfect example is any company (and there are many) who believe that good technical documentation can be cut in the budget, because support can handle the issues, only to discover that one call to support costs far more than creating good documentation in the first place. Content Strategy 101 offers some insight on the fallacy of low-cost documentation.

So with today’s evolving documentation practices, we have to work hard to improve that documentation mousetrap. We don’t build manuals any more. We don’t ship CDs with pages and pages of tiny-print leaflets of unreadable instructions, so what are some ways to make our ever-evolving documentation relevant?

I suggest that there are a top 5.

Of course there are more like a top 100, but if I put them all here, I will have blogged myself out of a job and I’ll be the irrelevant one, so stay tuned for future blog posts with other super-engaging titles like “Top 5 ways to Test Your Doc!” and “Coordinating Internal Systems!” you get the gist.

For now…


Give User Examples

In Online Documentation, unlike print matter, there is room for Use-Case. Scenario-Based Documentation is popular now, so learn to make it your friend. The SBC is an online user’s friend. Embrace the SBC.

Examples are a superior way for end users to see and experience concepts that are difficult and new. An end user learning new software can experience the software much more easily with a walk-through than with just a third-person explanation.

Switch to second person and allow for a full flow. For example, “When you click on the water icon, you see the mermaid swim across the screen.”


Use Diagrams and Images if Possible

This seems like everyone already knows it, and yet they don’t. OR, if they know it they are not doing it. When the internet was young, everyone was slapping pictures on everything. All of a sudden, we are back to wordiness. I’m a fan of “a picture is worth a thousand words.” Explain a process with a picture, will ya? Not everything needs a photo, but a process sure needs a diagram. If you can minimize the complexity of your documentation by offering a table, do it. Or if you can make it a bulleted list, get on that.


Assume Nothing

You may not know your audience, but presume that they know even less than you do. If you think that the average user is pretty well-versed in computer skills, and you want clutter-free doc, at least take a moment to offer a hyperlink to a basic skills set in an appendix for those who know pretty much zero. Change your mindset to that of a brand-new user who has never seen this stuff. Fully document the process from beginning to end, and then go back and follow your process.


Anticipate Difficulty

Try to break your stuff. You have QA testers who have tried to find issues with the software, so you should try to find issues with your documentation. If the software you are writing for has defects (end users call them bugs) you’ll need to document workarounds for those, providing useful ways to save your users calls to the help desk or support, and proving yourself to be a very useful doc writer. This is a tender spot to be in with developers and testers, but your relationship here counts.

If you are working in an Agile environment, (most of us are these days) you can usually test as you go. You’ll get smaller chunks of doc to try out, in smaller increments, which is nice. Find the zones where your doc is unclear, or could be clearer, and prop it up.


Explore New Technologies

Hey, Documentation is expensive even when it is done correctly, implemented flawlessly and delivered on time and on budget. Doc departments cost money, and we are not the primary product. Is it any wonder doc departments are often trying to justify our very existence?

New technologies will perpetually be the key to creating more effective documentation that is less expensive to develop. New tools are opportunities to reduce time and the cost of the whole process. Look into text-to-speech. Look into better visual editors. Check out the latest in fill-in boxes, component editors, macro checkers – the whole shebang. You will cast aside 90%, but you will find some of them are magical. Remember the little paperclip that sounded like it was tapping on your screen?  Annoying, yes, but nifty nonetheless. Remember the first time you opened Power Point?

Holy cow! Remember the first time you checked out GeoCities?   Now think about the first time you edited in Adobe. Or edited your content into 140 characters.

Check out all of the ways to document.

Myriad. Seriously. Mousetraps upon mousetraps.

And the mousetraps are getting better. The mice are smarter. But the mousetrap builders are pretty smart, too, and we are acquiring better ways to go about it. So don’t move the cheese, just build a better trap. Follow the documentation, and you will have all you need to get the job done right.

Behe's mousetrap




Busy is Not Productive if It’s Just Busy



All too often, and more so on the weekends, we find ourselves saying, “I’m too busy to do that,” or “I’m too busy all week at work,” and other phrases quite similar to that. The Next Web writer Sean Kim recently wrote a column titled “Why telling ourselves we’re too busy is bullshit,” highlighting the idea that busy is different from productive.

We are asked to be productive all the time. In our jobs, the management structure or clientele certainly demand productivity. At home, if we are not productive, we have creeping lists of things that simply never get done. Busy-ness can get in the way of that productivity if what we are really doing is postponing the important things, or mis-prioritizing altogether. Kim points out a list of attributes that separate busy people from productive ones, including what in my industry is called “WIP,” or work-in-progress.

People who have too much work-in-progress always seem busy, and in fact they probably are quite busy, but the to-do list does not shrink. Having many projects partially finished is far less productive than banging out tasks to completion, one or two (or when necessary, a few) at a time. In the agile software development community, limiting WIP is a celebrated attribute of employees and teams.

According to, no one can be too busy if they prioritize properly. Lifehack contributor Conor Neill writes, “if you have 3 priorities, you have priorities. If you have 25 priorities, you have a mess.”

But how can priorities be rearranged? Sometimes, there is just a lot to do.

Author Gary Keller recently wrote “The One Thing,

a book about how if you can identify the one thing that you can do that will make everything easier to do, your productivity can soar. What One Thing stands between me and a productive day? Or, what One Thing can I get out of the way, learn, achieve, etc., that will exist in harmony with the other things on my list, making everything that much easier?

Identifying that one thing leads away from WIP and directly to productivity.

Reprioritizing goals can often be connected to that “one thing,” but it is also a heavy-hitting tool in the attempt to limit WIP. If I say “yes” to too many things, surely my brain perceives that they are nearly all of equal importance, and I try to attack them all, but I am setting myself up to fail. I will be busy, yes, but I will not be productive. The skill of saying “no” to some activities, tasks, or events is a difficult one to master, particularly for those of us who have families – or even dogs. The desire to keep everyone satisfied, from partner to kids to Rover, is a strong one. Warren Buffet is credited with saying that the definition of integrity is that you “say no to most things.” Hey, there is a reason those pro/con lists were developed in the first place!

im-too-busy Another aspect of busy not equaling productive is that busy people tend to tell you how busy they are. Feeling productive is not the same thing as actually producing, so just the action of being busy does not, cannot, suffice. When we want to really accomplish something, we make time to do it. We focus on the task at hand, make it important, and grind it out – sometimes to the exclusion of other things. And that is just fine. Action supports production far more than words do (unless you are a writer, in which case the words are important – but not the words, “I’m busy making excuses for not writing because I am too busy!”

In his book, The Path to Extraordinary Productivity, Gary Kogon claims that people have gotten far too proud of the sensation and claim that they are busy. visits this in their Inc. Video, “Productivity Playbook.”

Barbara Hemphill, of the Productive Environment Institute, has exceptionally good advice for remedying the “busy” out of our productivity. She claims that while busy people have very long to-do lists, productive people carve out the three clear goals of the day, and write those down instead. Hemphill insists that “if you consistently do not get those three things done, then it’s time for some serious conversation with yourself.”


She recommends that in order to be truly productive, we should return to (if we ever were there) “single-tasking” as a way to remove ourselves from multitasking. (Back to that WIP idea, here we go.) By limiting the day’s prioritized tasks to three, we are more likely to stay on task and not allow distractions to sway us off course. The end result? Results. The ability to say, “I did X,Y, and Z today” instead of lamenting that A, B, and C are still on our task lists.

The takeaways? I think there are a few. Learning to manage time productively is more than just good time-management. To be truly productive, we have to show that things were completed. An author talks very little about what she is writing now, but is super-proud of what was just published. The complete work is the thing.

So in order to do that – Limit the number of tasks we take on.

Prioritize the tasks we agree to

Agree only after considering “no” as a viable option

Remember that there is no prize for being busy, but there are                                                          rewards for work  completed.

So now, I suppose that in order to cross one item off my three-item list, I should now hit the “publish” button and send this one in. Tomorrow I’m going to be really busy…No, but I AM going to be very productive!



Why Developers Make Really Bad Tech Writers



Every now and then, I come across a blog post or other article or column declaring that technical writing for software development is a dying career, lamenting that all of us in the tech writing game should plan our exit strategies and admit that if a product is truly well-designed, our services are simply not needed.

Surely, in some product cases this is true. However, in many high-level software instances, I defy you to successfully install and run the product without some help from your friendly neighborhood tech writer. I pose this challenge because developers think and behave like developers and users think and behave like users. There is a chasm as wide as the English Channel between developer and user, and only the talented technical writer can provide transport safely across.

It’s not that developers are incapable of writing well or that they cannot write documentation, and it is not that users cannot ferret their way through intricate software. Developers could write supporting documentation – IF they weren’t developing that particular product. But alas, developers are too close to the products they are developing. They lack adequate perspective when it comes to their fledgling software, and they have great difficulty seeing it from a user’s point of view. The software, to a developer, makes sense. Developers arrive at a use-stance with some assumptions about functionality and behavior already in hand. So they make lousy content writers because they can’t see it from a user standpoint.

A shift needs to occur in order to artfully create usable content. A developer’s view is, “this is the product, and here are its amazing features,” whereas a technical writer will approach the very same thing from a perch saying, “here is how to do some amazing stuff with this new product.”

Technical writing shifts the focus to a user-centric view that is very difficult for a developer to take. It’s also no small thing that technical writers have been trying to master language, grammar and syntax for the better part of their educations. It’s a sure bet that developers have taken English courses as part of their college education. There are no programmers out there who are illiterate, don’t get me wrong. I work with some really smart people, no doubt about it! But when I tell them that all of our documentation is better perceived in active voice rather than passive, I tend to get a room filled with glassy-eyed folks who really want to get back to their work creating dynamic rules instead of determining whether or not they need a helping verb.

Technical writing in the software field is far from dying. What it IS doing is merging – tightly – with user interaction. It is absolutely, inarguably true that users wish they did not have to read so much in order to get started when they have a new product in their hands. So when we design documentation, we had better design it to work well. Lean documentation is essential – Strunk and White and their mantra “omit needless words” were not kidding.

Working with developers is an art. Letting them do what they do best, and making way for what writers do best, is a science.

I’ve argued more than once that mastering a given tool, like Dita or Framemaker, is fruitful but only if the situation calls for it. I have a totally separate set of tools that I use in my job, and they may or may not prove to be portable, but the skill that is 100% portable is that I can talk to, work with, communicate with, and understand – developers. I let them do their jobs with great enthusiasm, and I encourage them to let me do mine. It’s a synergy that keeps us all smiling, and pushing software out the door at a high rate of success. I work on UX, I design good doc, I focus on usability, I listen to my data.  I look at those sills that simply crackle with career stability. I let the developers tell me everything else that is important. And…I don’t make them write too much. Why? Because they don’t really enjoy it anyway.

And developers make really bad tech writers.

At the Corner of Gridlock and Unlock

Lily Tomlin did a great character in her film, “The Search for Signs of Intelligent Life.” The character was Trudy, the bag lady. Her monologue has been repeated by amateurs all over, but I wasn’t able to find Tomlin ever repeating the scene.

(This one’s pretty good.)

The monologue has alternately been dubbed “Standing at the Corner of Walk and Don’t Walk.” It’s that good – it has its own monologue name.

My home city of Pittsburgh, PA, is at its own Walk/Don’t Walk corner right now. We are at a better corner than a schizophrenic, convinced she once worked for a snack dynasty, though. We have an infrastructure problem to solve, and we just might get a whole buncha money to help solve it, and the technical expertise of Google’s mobility program, Sidewalk Labs to help us do it.

What’s at stake?

Well, as Sidewalk sees it, there have been some pretty big revolutions (three, to be precise) in city-building, and those revolutions have come at a high cost. If they can develop a more cost-effective and efficient solution to the sure-to-come fourth revolution, it will be…well…revolutionary.

steam engine

According to Sidewalk Labs, we first moved people around and developed cities thanks to steam. (Think locomotives!) That makes perfect sense when you think about Pittsburgh – for crying out loud, we wouldn’t have any trains and train systems if it wasn’t for steel, and steel is the very industrial backbone of Pittsburgh. (Hello? Our football team is even named the Steelers!)

Then came electricity, which granted us lights for interior spaces, which is also a darn good thing for Pittsburgh because with all that coal dust and smoke from the steel mills, we sure needed electric lighting. We even needed it to light the interiors of the steel mills, but probably more importantly the homes of the likes of innovators Andrew Carnegie, Andrew Mellon, and Henry Clay Frick, who paid for most of the development of the steel industry and the urban development anyway, despite the many controversies surrounding their methods. Remember that guy who said Pittsburgh was like “hell

hell lid
Pittsburgh, 1872

with the lid off?” (For the record, it was James Parton, a writer from Boston, who penned it in 1868 – we still don’t like him.)

So electricity is the second revolution. Then along comes the automobile. That’s a major issue in establishing urban living, to be sure, and if you haven’t seen Pittsburgh’s topography, you can’t possibly appreciate just how revolutionary the automobile is to comfortable urban development.

We are a city built at the confluence of the Allegheny and Monongahela Rivers, which places us in a basin of sorts, carved by mighty rivers, flanked by mountains which are gorgeous but steep and majestic, necessitating roads that wind, angles that astound. Pittsburgh as a city maintains 700 sets of “City Steps.” These are cool, essential components of a pedestrian infrastructure connecting neighborhoods that are steep, and which would otherwise have impassable vehicular connections street-to-street without winding a mile or more.

The steps are great, but without a car to spirit you over Mt. Washington or across the mighty rivers, you’d be stuck living along the rivers in what we lovingly call “the Golden Triangle,” and that would leave very little land to develop into the beautiful urban spaces we now have as both the North and South Shores.

Instead, our city planners and companies like Sidewalk Labs see a fourth revolution on our vista, and it’s a digital one. We already know that things like crowdsourcing apps (think Tiramisu) can help us transform transportation and smart living (think Wink) can integrate into our daily lives, but can they help our daily commute in ways that truly make us more secure, solve our most pressing problems as a city, make us safer, respect our privacy, and bridge the gap between city of today and city of tomorrow?

It seems like that is what they wish to set out to do, and since Alphabet-style (nee Google) minds and energy levels are behind it, I wouldn’t be the least bit surprised that the rate of success feels quite high.

I’m looking at just one idea for now – it’s their notion of Flow.

Sidewalk Labs sets out to wrestle congestion. I’m an avid cyclist. I still harbor a bit of fear in city cycling because, hey, people get killed on bikes. It’s real, and it’s scary. It’s expensive to commute, though, and I love the environment, so if I could be a part of a solution to the rat-race commuter congestion issue, I’d sign up in a heartbeat. Flow analytics with Sidewalk Labs is looking at Pittsburgh as one of the finalists in a 7-city competition to use analytics and messaging to increase efficiency of roads, parking and transit. That is our Walk/Don’t Walk. Can we move from being one of Seven Finalists to being “the one?” Will Pittsburgh get the final rose?

So I’m asking myself, “Hey, as someone who wants to be able to bike around the city better, how will this help me?” And my answer was easy – if there is less congestion in general, I get back and forth safer, and the mobility issue in general is an improved experience. Win-win-win. Drivers and cyclists together are happier people. Mayor Peduto has been working hard to integrate better, safer bike lanes in our city, and although not all of the data is in, the results so far are pretty great. More bike commuters, with happier faces, and very little (if any) added congestion in our downtown corridors.

They have this interactive messaging (this is where the tech writer in me totally geeked out) and dynamic parking (woah) along with dynamic transit (everything green and eco-friendly about me went berserk now.

So here’s the gist of why this tech writer went all off-topic and posted about an urban-development app on a Tech Pub kind of page. This is the sort of thing every city should get behind. This is the kind of Justin Trudeau, Portland-can’t-beat-this, nobody can oppose this idea kind of stuff that makes cities great. This makes life great. Who doesn’t want a smoother commute every day? I mean, unless you already work at home in your pajamas and only have to walk to the grocery store, the dentist and the veterinarian, this seems too good to be true. And when this thing happens to be available near you, do the work. Participate in the data-gathering, because this is not big-brother in the way that some folk might cast a side-eye toward. This is the stuff dreams are made of. Beautiful, blissful, traffic-jam, I found a parking space dreams.


Pittsburgh, 2015 – We are much, much cleaner than Hell now!



International-Womens-DayI know I just posted yesterday, but I have had a working draft of this piece in the hopper for a while; it just never quite grew its feet, as I like to say. And I can’t put a piece on the blog until it has its own feet. But today, being Women’s Day and all, the piece found its feet.

I recalled Isis Anchalee – remember her? She’s the bright, talented, strong, and yes, beautiful platform engineer from the Tech Startup OneLogin who asked her to participate in their ad campaign, which then sparked the #ilooklikeanengineer hashtag movement. It didn’t take long for the misogynists among us to determine that Isis was simply too pretty to be a “real” platform engineer. There’s just no way a smart brain could be housed in that attractive body.

The movement caught on fast, but it has faded just as quickly. It’s not enough to repeatedly have lists like Forbes top 30 women under 30, although that’s a great list. I say it’s not enough, because when a company like Microsoft reveals its diversity numbers to reflect the staggeringly awful truth: over 75% male and 60% white, with an only 29% female workforce globally, that’s alarming. And then comes the real hit: only 12.5% of Microsoft’s senior leadership in America is female. (Source: Forbes). This is happening even though we know that women are generally better at coding tasks than men.

But we also have to reveal the truth that, according to the US Department of Labor, only 12% of Computer Science graduates today are women.

Why? What about this environment is blocking women? Are we really just not cut out for this field?


Not really. According to Gayle Laakman McDowell, author of Cracking the Interview, and a coder herself, it’s primarily that girls, when they are girls, are mostly sent the message that, “hey, this stuff is not for you.” Subtly or overtly, young women are, from a very young age, steered toward the humanities while young men are steered toward hard sciences. (We’ve known this for a long time, but I’m providing ethos here. I’m a writer, so to show you I have backup, I provide a subject-matter-expert, okay?)

So we tell girls and young women that they just don’t look like coders. They look like teachers, they look like nurses, they look like bank tellers or whatever, but they do not look like they fit in the cubicle-hive style pressure system that is software development or platform engineering. Is that it?

In other areas of their lives, we are telling them to be “totally natural,” or to be proud of what they look like. We tell them to embrace their body types and to live their lives with gusto. Kate Winslett recently signed a modeling deal with L’Oreal that has a “no Photoshop” clause, and we applaud this honesty and truth to herself.

But we haven’t told young girls that if their true beauty is in writing code, that they are totally entitled to that gorgeousness?

The percentage of women who work in tech companies remains consistent, at around 30%. So there ARE women who do this stuff, but it’s stagnant. It is failing to grow. Even though more women go to college, and an even greater number of women attain graduate degrees, the percentage stays flat. Now, what I find truly remarkable is that the percentage of women in technical or leadership roles – roles where they can actually influence the direction the company takes, is even lower. This difficulty may be the result of well-known sexism in the technology sector, or at least an unwillingness to combat it. The New York Times ran a great piece in April of 2014 called “Technology’s Man Problem,” documenting just this trend, and not much has changed in the last two years, but some things have.

It is not just a matter of moving more girls into a pipeline of studying STEM, because the high rate of attrition in tech moves them right on out the door just as quickly. Teaching women and girls that the tech field is appealing, lucrative, and open to them is not the quick fix we hoped it would be. Instead, fixing the culture that says, “you don’t look like an engineer, coder, tech writer…” THAT is the solution, or at least part of it. In the UK, a campaign called “This Girl Can” strives to connect young women through physical activity and inspiration, while here in the US, Target recently launched an ad campaign called Target Loves Every Body.

I believe we need a culture shift that defines, or redefines, the landscape to show that coders look like lots of things, and writers look like lots of things. Women in many careers have been trying to reshape their images from Hollywood to magazine covers, so why not in Silicon Valley, too?

Women helping women is the key to confidence and the key to success. If tech culture is going to change, everyone needs to change. The emotional and professional cost is simply too high not to. So on this, Women’s Day, the challenge is to reach out to a woman in your field – or a woman not yet in your field – and mentor or inspire, encourage or reassure her. That is how it gets done. Make a pledge to yourself that you will make room in tech for one more young woman, or that you will make additional room for one more established woman. It’s a jungle in here. Even women who have worked in here for years can get lost in the tangle of tasks, so have lunch this week, next, and next month too. There is networking to be done, and we could all use it. Today does not need to be the only Woman’s Day you have this year. Let the women in your life, especially in your tech life, know that they LOOK like accomplishers, achievers, builders, and leaders.

And then, if you are a woman, make sure you accomplish, achieve, build, and lead.