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

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

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

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

What to Include in Release Notes:

New Features and Functions

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

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

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

Bug Fixes                                                                                         

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

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

Deprecations                                                                    

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

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

Why did I bother to put this little guide together?

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

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

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

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

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

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

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

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

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

 

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 Chron.com, 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-building 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 generally 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.

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

Clear and consistent jargon-free messaging has to become part of the company culture. If we can’t get past all of the marketing pizzazz, which is necessary, and the emotional protection, which is also necessary, then we weaken the relationship that we strive to build. 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.

 

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 (Fortune.com 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.

Women who are encouraged to be leaders have to internalize that role and believe that they can be that role. Leadership is an identity, not just a title. Part of what stymies women in escalating toward these roles is the “human tendency to gravitate to people like oneself,” in which case women are lacking in examples of other powerful women (Ibarra, 2013).

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, which then assumes the “trailing spouse” (wife) who can pack up and move along with the new job offer. A wife who has no career can easily pack up with the kids and relocate with little trouble to follow the new promotion opportunity. This work-value is much more difficult if the “trailing spouse” is a man with a career trajectory similar to that of his wife.

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.

 

 

 

 

 

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

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

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.

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.

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?