Tag Archives: strategy

techpubs work

Career Focus: Community Documentation

I gave this interview via email to Mandy Morgan, a senior at Missouri State University this year, majoring in technical writing with a journalism minor. She wrote up a memo for a career focus class based on the interview and I’m repurposing the Q & A here.

Q: For starters, I was wondering what skills you have that you didn’t learn in schooling that helped you succeed in the professional world?

A: There are pretty specific web and server skills that I had to learn after finishing my education – mostly because they’re very fast-moving technology that I had not needed to try out during college and grad school. Every tech writer I’ve met has a different path into tech writing, but mine is a bit traditional. I got an undergraduate degree in Chemistry and spent a summer in a test lab, doing quality checks on infant formula. I found I was interested in the instrumentation manuals and how they were written, so in my final year of undergrad I started researching technical communication. As it turned out, there are graduate programs in tech comm so I went to Miami University in Ohio and got a degree. Part of the degree program was an internship, and I learned about online writing and HTML had just started to be a standard for the web. Since then, I’ve always worked in software documentation at large and small companies. I have had to pick up technology skills constantly along the way.

Q: How important was it for you to learn the technology before you started your job and what systems have you learned during your professional experience?

A: In my current job I learned much of the technology on the job because I hadn’t needed to know cloud computing prior to joining Rackspace. One attribute of technical writers in general is that we learn quickly. So in my case, it was more important that I could grasp concepts quickly rather than learn the technology prior to starting the job. I took this job about 2 months after the OpenStack project was launched, so really it would have been impossible to learn about
OpenStack, open source cloud computing, prior to starting. A clear understanding concepts and systems should be applicable no matter how the technology changes through the years (or months or days!).

Q: How often do you get feedback on the work that you do, and what form do you receive your feedback in? Who are the main people that you interact with (whether this be a team or SMEs, etc.)?

A: Getting feedback (and future direction) can be tricky in documentation because you want to write for certain users and audiences rather than for the team that wrote the product itself. I love it when I hear people say, “I no longer work for development. I work for the user.” They say it with disruption and evolution in their hearts and minds. They fully intend to serve the user the best they can, and user feedback is the most valuable type. I also believe in using web analytics to gather feedback on how effective your deliverables are.

Comments are a great way to get feedback immediately on a page you’ve written. Comments connect users to each other and to the authors of the content.

So in my case, I try to interact with community members and users as much as I do with developers who are subject matter experts.

Q: How important would you say knowing grammar and mechanics rules are?

Honestly, as quickly as the code moves, the documentation also has to move, so knowing grammar and getting mechanics right the first time are essential to having high-quality docs done quickly. I also review a lot of community contributions and need them to write English very well. I can serve as a grammatical editor during the review process but ideally the writer is very good at it already.

Q: Did networking play a large role in the job process for you and where you are today?

A: Absolutely – every job I’ve gotten has been a direct result of networking either through professional associations or through volunteer work on open source projects. I hold strong beliefs in networking being a constant activity – not for my own sake but for the good feelings I get from helping others, which I suppose is still self-centered.

Q: How much time did you have to devote outside of the work place to your job when you first started and now?

A: I love the flexibility that writing as a core skill in my career gives me – I can write from home, write at any hour, and the equipment I need is something I own and like to use already. I also love that I can attend user group meetings outside of regular work hours. I also get to attend twice-yearly in-person meetings with the community project contributors, which is just part of the job, not necessarily outside of the work place. I guess my answer is, the job doesn’t have an “inside” and “outside” of the workplace since it is so collaborative and community-oriented.

Q: And the ever famous questions, what struggles do you face with your job and what is the most rewarding aspect of it? Is the track that you’re on now, the one you planned to be on after school?

A: The struggle isn’t so much with the job itself but with the need to raise a family and have a home life when we’re so connected constantly. My daily  prioritization and focus is something I struggle with. This job is a dream job for me, though, it’s so rewarding to work in a community towards common goals. Plus Rackspace firmly believes in using your strengths to do work you love. I’m surrounded by really smart helpful people.

A graduate degree was my path to get to the awesome job I have now, but I don’t know that it has to be the “right” path. With the upsurge in open source documentation groups, it seems an apprenticeship in open source doc would still lead you to the right jobs and connections. After undergrad, I discovered technical writing, and had a very planned track through grad school to get to where I wanted to be. Even so, the career paths in technical writing in particular have a stodgy character to them sometimes. I’m more innovative and experimental with technical writing than the general group of technical writers subscribe to, and sometimes that causes twists and turns in the path.

Q: What is your title?

A: My business cards read “Content Stacker” which is a play on words – at Rackspace we are called Rackers and when you work on OpenStack we are called Stackers. So since I create, curate, source, and sort content for OpenStack, I call myself a Content Stacker. My title at Rackspace is Technical Writer.

Q: What piece of advice could you offer to students on being successful in the tech writing world?

Become as technical as possible while maintaining a user advocacy viewpoint. Be willing to experiment and definitely embrace the web and mobile devices as delivery mechanisms for information. Do what you love!

techpubs writing

Repurposing and Reinventing Content

I think we’re all adjusting to a new way of learning thanks to the copious amounts of information available. You don’t have to take a class, you just have to do it. And to “do it” often times you need to find a detailed-enough hands-on project to do, or else you won’t learn.

Photo courtesy emdot on FlickrHere’s a case-in-point. Have you fiddled with the knots you’re supposed to tie for your son’s Boy Scout badge, or tried to secure a rock-climbing harness? You won’t learn it unless you try the knot, again and again. I believe that hands-on learning applies to computer and technology tasks, even if they are abstract. When I started with a new version control system, the commands were fumbly to me, and I constantly used “crutches” to get through the task. At first, I had to repeatedly read a wiki page and follow the steps to the letter. Eventually, though, the commands become second nature as I tried, and tried again.

With this in mind, how can you take “learning” content and turn it into a more animated walk-through which will then lead someone to do the example? Let’s take a look at the Animated Knots iPhone App. There’s a great article on the Statesman about an Austin family who have taken web content and turned it into an iPhone app. Austin is a hot bed of mobile development, I think, and this is a great example of a successful mobile app.

Here are some of my observations about their success.


First, they sound like they use persona-based design. They had four ideal audiences in mind – climbers, fishers, Scouts, and boaters. A surprising additional group they discovered later and were proud to serve were fire fighters or rescue workers.

Labor of love

Also, they gave their content time – the original site was a labor of love for ten years. With four million website visitors a year, I’m sure they used both hard data like web analytics along with soft data like the incoming success stories from their main audience members to improve the content in that time.

Visual appeal

They also use a lot of photos – which they shoot themselves. From the Statesman article:

All of our animations are based on individual still photos linked to form a sequence that shows a knot tying itself; the more complex the knot, the more photos and time required to illustrate it properly. Some knots may require only a few images, others as many as 25.

If you’ve worked with images in your technical writing endeavors, you know that this type of training is a lot of work. Knowing exactly how to break a task into steps, knowing what angle to shoot from, and knowing whether you can insert a substep, these are all difficult but if you’re good at it, it’ll show in the training product.

Seasonal timing

Their app was featured in the iTunes store during the U.S. summer months, which was just the right content at just the right time for people enjoying the outdoors with their iPhones in tow.

Existing in an ecosystem with lots of adoption

The reporter, Omar Gallaga, asked Martin Grogono, one of the family members maintaining the site and app, about the platforms they had released on. Martin explained that the iTunes store and high installed base of iPhone users was a boon to their app. They’re considering the Android platform but haven’t pursued the Windows phone quite yet.

Content tidbits from a Community Roundtable report

Photo courtesy M i x y on Flickr using the CC By 2.0 licenseI’m reading (with vigor!) the The State of Community Management Report: Best Practices from Community Practitioners
from the Community Roundtable
, and finding so many wonderful tips about content from people who are community managers. I had to start a list of items that are relevant to technical communication and web writing to share. I naturally tend to target technical communications when I interpret the report, but this report is rife with content strategy.

I agree with this statement, and I think it means a positive impact on technical writers and web writers who are paid to create content by businesses.

The percentage of content that is desirable and
feasible to be formally produced versus community-generated
will have a big impact on resource and
budget planning. This aspect is likely to change – often
dramatically – over time, although it should not be
assumed that content should ever be exclusively

I personally haven’t found that completely community-generated documentation will serve most business goals. In the case of FLOSS Manuals, though, the community-generated content meets the main purpose of supporting and documenting  open source software. Still, hiring professional writers makes sense when you need to create content that meets very specific goals for a community, whether your goals are raising awareness, troubleshooting, or learning.

Now, this particular comment puts a bit of a stake in the heart of technical communication’s beloved single sourcing. I like the idea of associated content for technical writers to create. It’s branching into new media, such as audio or video, while still valuing the technical content that you work so hard to create. It’s not that one births the other, but rather the two types can compliment each other.

Instead of directly repurposing content from one format to another, create
associated content. For example, instead of turning a white paper into an
audio transcript, create a podcast discussion about it with the author.

Another line that causes me to press pause and ponder for a bit:

People seldom form relationships with text alone.

Instead, offer images, video, or music as part of the user experience in order to grow relationships. Fascinating.

And finally, the one that might be the toughest for professional writers, copy editors, and technical communicators to accept:

Learn to accept imperfection. Concentrate on making content interesting
and relevant rather than perfect. Imperfection actually allows community
members to better relate to it and engage with it.

And with striving towards imperfection as my excuse, I’ll close out this blog entry and encourage you to read the report for yourself, drawing your own arrows from the quiver and targeting what is important to you.

Wow, oh Wow – Book Reading at SXSW Interactive!

I’ve been given a 20-minute book reading opportunity at SXSWi! I’ve been to SXSW Interactive at least three times over the past five years, and I’m a huge fan of the conference. So, when I saw an email in my inbox from Hugh Forrest, the organizer, I ran around my (home) office with glee!

Here’s a description of the reading, which is scheduled for Tuesday, March 16th at 12:30.

A reading by the author of Conversation and Community: The Social Web for Documentation. This book brings together the worlds of technical communication and social media. It shows how technical communicators can effectively use social media, and describes why quality technical content is essential to a successful social media strategy.

You can add it to your schedule using this link. I’d love to meet you there, and would love your suggestions for what to read from my book. I’m just amazed to have this opportunity and can’t wait to hear questions and comments about the social web for documentation.

Pilot or not?

While doing some research for LugIron, a startup here in Austin where I serve in an advisory role, I found a slideshow discussing signs of successful community launches by Joe Cothrel, a VP of service at Lithium.

Now, what they mean by “community” is a larger than 5,000 person audience, enterprise-type (B2B or B2C focused communities), and containing primarily forums and blogs (followed by everything else.) So, it’s not quite the same as the wiki communities that I’ve studied and participated in. But, what’s interesting to me is that one of his Warning signs on page 8 is a quote from the enterprise:

“We want to do a pilot.”

Huh? Really? Wanting to do a pilot is a warning sign of eminent failure? I guess with blogs and forums, you would want full dedication to the efforts and the goals of the community. But with wiki communities, I think a pilot is a great idea. Pilot content, pilot collaborators, pilot wiki.

What do you think? Do wikis fold up easier than forums? Are pilots getting a bad name in corporate-sponsored communities? Is this a case of the vendor wanting full dedication in their sales engagements?

Content strategy and web writing

contentstrategyforthewebBoy, it must be getting harder and harder to be a web writer. I’m reading Content Strategy for the Web, and the web writer job description is intimidating! The quote that stuck with me talks about the Web Writers Real Job: problem solvers who write well. I do hope this quote describes many technical communicators today.

“The web writer’s mission? Useful, usable content that’s also enjoyable. It’s her job to begin a conversation with the reader that results in mutually beneficial outcomes all around. A problem solved. An article found. A connection made.”

All of these outcomes can be tied to thinking about technical documentation as a conversation starter. My book talks about social media enabling those conversations. Often, though, social distribution is simply the technique, but the web itself is the medium. When writing in that medium, we must be the best writers with the most considerations taken into account while writing. Search engine optimization. Style and voice when writing for the web versus print. Information architecture, organization, and label naming. Maintaining a content inventory. Auditing and editing content. Testing content. Handling workflow, reviews, and deadlines. The list could go on and on.

And here’s the thing. People are not backing down from figuring out a great web strategy despite the challenges, and finding great success. I had a great lunchtime conversation with Brian Massey, the Conversion Scientist. He basically mapped technical publications’ typical goals to the personas that help you encourage a conversion. Fascinating! He describes four personas typically used by marketing writers on the web in the blog post, Relate to Four, Connect with Thousands:

Methodical – Probably the first persona to come to mind when talking about traditional technical documentation, perhaps not even all that web-hungry. They want proof, answers, solutions, in an orderly fashion. They’d probably download and read a PDF file if it’s offered.

Competitive – They want information that will make them better, smarter, or cutting-edge. They may be the implementer at a company who will train others in the product you’re documenting, so they’d want scenarios that make them look good.

Humanist – To me, this type of persona, one who looks for relationships and the human element, might be difficult to deliver technical documentation to. They might pick up the phone to call tech support faster than looking up a question online, unless a community is behind the documentation that they can relate to. The humanist may also appreciate case studies that help them relate to a real story.

Spontaneous – They want to know the answer quickly and move on, so scannable headlines and topic authoring with any topic being a potential entry point will probably work well for them.

I’m definitely looking at my web writing in new ways. Not just in terms of deliverables, but also in terms of the content I can deliver to the right audiences, to help them meet their goals.

Content strategy – so much to learn

I just ordered Kristina Halvorson’s (@halvorson on Twitter) book, Content Strategy for the Web after viewing “10 things every business person needs to know about content strategy” slideshare.net presentation (by Melissa Rach). Powerful stuff!10 things every business person should know about content strategy

View more presentations from mrsruble.

Reminds me that I need to get cracking on a presentation to supplement my book. I’ll finish up this blog post for now. 🙂

I learned a lot just by clicking through this slide deck so I am anticipating a good education from the book as well.

Content strategists seem to have interesting conversations around the #contentstrategy Twitter hashtags. I learned that PBS has a Chief Content Officer and apparently so does NPR.

I enjoyed the post with notes about content strategy on I’d Rather Be Writing, Three Questions To Start Thinking Like a Content Strategist. The link list at the end is very valuable. Another fascinating set of links for learning is on this Friday content strategy: installment 3 post. It has this excellent warning right up front: Caution: reading the following may make you passionate about content strategy and knowledgeable about recent content news.

So, consider yourself warned. Starting to read this post and clicking through to all the links may lead you through a most fascinating journey to learn more about content strategy.