Tag Archives: content

techpubs writing

Developers, Writers, and First Jobs

I constantly try to network locally with Austinites, and I’m meeting more tech writers with diverse backgrounds. One of Austin’s slogans is “Keep Austin Weird” and while our writers aren’t necessarily weird, their backgrounds can be!

For example, I know of one award-winning novelist in Austin who writes manuals during the day and novels at night. Did you know that Sara Gruen was a laid off Oracle tech writer who wrote “Water for Elephants” during a National Novel Writing Month? Those are cool stories of a writer’s path.

At a staff meeting a while ago, we went around the room and answered the question, “What was your first job?” I had de-tassled corn in northern Indiana when I was 14, getting it ready for hybrid fertilization by pulling the tops off of certain corn stalk rows. Another writer had worked a summer in a detention center, and another had been a bartender. Our diverse backgrounds all brought us to the same place and time and careers and meeting room.

Lately I’m seeing more and more need to hire programmers and coders who like to write and are excellent at it. This Microsoft Programming Writer I job has a great section in it:

You are comfortable creating both code and prose. You have a passion for the web and its ability to solve real world needs and create connections between people. You know that there are many technologies that fuel the web, and you’re like a kid in a candy store when you play with new APIs and discover how they expand your abilities. Your real satisfaction comes when you successfully teach someone else how to use those APIs, though, through a blog post or talking at a meetup. You’ve got a knack for coding: you use patterns and practices such as responsive design, you know your way around jQuery and Modernizr, but you prefer to code in adopted standards. In fact, you occasionally read W3C specifications for inspiration. Maybe you hope to someday edit specs…

This feels like the direction I’m moving in, and I hope you’ll come with me as I pick up blogging again. I’m interested in developers and becoming more and more like one. I’m not going after it like this “Don’t be a jerk: write documentation” post, though I do enjoy that style on others. My style is more about exploring, experimenting, trying things, and retrying.

How about you? What was your first job? Did you imagine you’d be in your here and now?

content strategy techpubs work writing

Tools and skills in the red

If this isn’t a snapshot of our industry, I don’t know what is.

A couple of observations:

  • “Documentations” [sic] to me indicates an English-second-language speaker. Members listing that term as a skill is 245K, larger than the 107K “Technical Documentation”.
  • Looks like it’s an easy popularity contest winner for “Technical Documentation” over “Technical Communication” with nearly 5 times as many LinkedIn members citing “Technical Documentation” as a Skill.
  • Content strategy as a Skill listing is growing 16% year over year.

Fascinating snapshot. What do you think of this data capture at this point in time?

community techpubs work writing

Community Content Strategist

I’m considering a request. It’s a request for a new branch in content strategy. Now it’s odd to even start such a fork when content strategy itself is so new, so nascent that its molds are barely even formed much less any cookie cutting going on. But I think it’s needed.

My request is that we have a branch of content strategy that centers on community.

1. Give us a specialty focus on building community through the expert and strategic use of content.

2. Produce analytical methods that look at requirements for each community persona using content for their goals.

3. Enable the community members to become content strategists themselves, creating, maintaining, and designing killer content in such a way that it grows the community and builds the community and accomplishes the goals the community sets forth.

What’s the business case for a position like this in your company? Let’s start with business case for content strategy:

  • A repeatable process for content creation, publication, maintenance, governance, and careful deletion.
  • Methods for tying content effectiveness to business goals.
  • Measures for people who do this work, based on effectiveness of their techniques in practice.
  • Disciplines to avoid regression and stop old bad habits.

What do I do if I want to call myself a community content strategist?

Let’s start with what I do. I have a pretty unique job here at Rackspace. I coordinate documentation efforts and stack content into meaningful bundles across multiple “core” projects that help organizations adopt OpenStack as consumers or deployers. I manage the documentation project just like a core code project including doc bugs, task tracking, build tool debugging, translation efforts, and all continuous integration aspects of keeping up with a fast-paced software project. I support the wiki, support developers sites that publish doc strings embedded with the code, customize the search engine, seek new content and new contributors, run a monthly doc meeting, participate in all in-person Design Summits held every six months, and ensure the vision for the docs aligns with the vision of the project. The vision is to increase adoption for OpenStack to help Rackspace meet its strategic goals along with HP, IBM, RedHat, and many other member organizations investing in open strategies. I’m creating a repeatable process, and trying to make methods and design tools for content effectiveness. I’ve been doing a lot of work and research into collaborative methods and need to blog about the findings to share.


techpubs wiki

Why Wiki?

In OpenStack-land, the wiki was chosen before I got here. It has a couple of flaws for my vision for open source documentation, which became more apparent when I recently outlined my reasoning for what content goes where. By walking through the “what goes where” talk about documentation and audience, I realized something about the system we have set up (and will tweak more) and it’s this: a wiki revisions a page at a time, but our doc system with comments revisions a site at a time, namely a release at a time. It’s an important distinction to make so that you decide what a web “page” contains. It’s important to be able to articulate your needs for a web page and how it’s updated so that you can tell authors how much information you need in a page.

A page at a time is really tough for ongoing maintenance, when you don’t choose correctly the amount of information in a page. There are also difficulties with the rather immature technology in many wikis. Wikis were designed for simple editing, fast publishing. What if you have a sweeping name change? Anyone doing tech comm in a wiki knows that’s a headache for many wiki systems. What about a final spell check? Page at a time. How about search and replace? Page at a time. And let’s not talk about the times when you have to add an entire column to a table in an ASCII-based wikitext way. Your wrists will revolt, I assure you.

But an interesting expectation for a wiki that wasn’t considered when choosing the wiki is the need for comments on each page. Right now the only web systems for OpenStack that enable comments on a page are the OpenStack blog and the docs site. The docs.openstack.org site is built with DocBook XML with Disqus comments embedded on each page. It’s not quite perfect, as we’re learning as we go that not everyone wants to moderate every comment from every book on the site, and we’re still learning how to turn off hundreds of comments at a time, but it’s a great solution to a specific need. Yes, even the comment system selection needs an information architect analysis before you begin, but that’s the topic of a future post.

Ironically, our wiki doesn’t have a way to comment. So we just use it for project documentation and any comments on a project design are actually done in person at a Design Summit, which is coming up next week. Even with the great opportunity for in-person interaction at the Summit, I get the feeling there are more people wanting to “talk back” and give feedback. And certainly people want to receive feedback, to a point where they specifically bring docs to me and request publishing through the docs.openstack.org system due to the commenting system.

So what this meandering post is coming around to stating is this: You don’t need a wiki to gather feedback on your docs. Find a way to embed comments on each page and a way for collaborators to edit and you’ve got two of the basic end-goals done.

Now, make sure the end goals are known in the first place. It’s possible you need a wiki because your information would be best written a page or an article at a time. This statement is obvious when looking through your hindsight lens but difficult to be disciplined enough to state in the first place. Answer the question “why” about five levels down and it’s likely you have a solution. It may or may not be a wiki, but it’s certain that if you’re producing web content, readers have certain expectations about the content when they come to it.

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.

techpubs tools wiki writing

Even More Technical Documentation Wikis

wiki neon sign

Last spring I wrote up a blog entry pointing out some additional technical documentation wikis to add to a list I had in my “Wiki-fy Your Doc Set” presentation. A recent Twitter request asking for technical documentation wiki examples brings me back to both lists to try to compile an even longer, more updated list. These are in no particular order and the links were tested in August 2010. Other wikis are behind support logins but this list offers wikis that can be viewed without a login.

It’s no wonder I have to keep creating new lists. The examples are constantly changing. For example, the Facebook Developer wiki is being moved to another site.

Finally, if you are considering a wiki for technical documentation, I recommend reading my post, Hurdles and Hardships using Wikis for Documentation, reading Sarah Maddox’s blog, buying my book, and sharing your experiences with others. Here’s to enjoying the wiki journey.

techpubs tools wiki

Must Help Pages Live Forever?

I’m pondering the 1998 article, Pages Must Live Forever (from Jakob Nielson’s Alertbox) while documenting the content aging report in MindTouch 2010 (Read the spec here, read the user guide here).

With redirects helping stave off link rot, it seems that we can fulfill the wish behind Kristina Halvorson’s plea not to allow the web become like the junk-filled planet in Wall-E. Instead of piling up old versions of pages, the links stay fresh while the content might age a bit, like a fine wine.

For help content, I can list reasons that older content might be just fine, no need to send off alarms.

  • Software that has classic features that were well documented in the first place, those pages can be static.
  • Pages that haven’t been updated but are still oft-visited I would consider to be fresh, not stale. As long as the comments don’t indicate a problem with the content, it can be considered fresh.
  • Depending on how well it’s resourced or energetic it is, your writing staff and community can only add a finite amount of content per week (or month). So the percentage of old content may be higher than the percentage of new content. That ratio is probably okay as your site ages. The mark the report sets is two years (24 months), then the content might be “old.”
  • Depending on the scope of the aging report, an older product would have older help pages. Filtering helps you tune in the grouping of pages where you might be concerned about stale pages.

Two years would be a long time in a web application’s life, but perhaps not so long for an enterprise application. As usual, the answer to “Must Help Pages Live Forever?” is “It depends.” The real question that I’m trying to answer is “When are Help Pages Stale?” I believe two years is a valid and reasonable line to draw. What do you think?

Elsewhere on the ‘Net

I haven’t done a round up of other places I’ve been writing lately, so I thought I’d offer a roundup of articles I’ve written for other sites.

What I’m writing

10 ways to motivate employees to use your CMS – Fierce Content Management

As a content strategist, what motivations help you meet your content goals when integrating a content system? Often the tool selection gets the most attention, yet the motivation of contributors is going to make or break the success of the project. Motivation is a psychological feature–a willingness to act that precedes behavior. You might think of a points system with rewards as a motivation system, but rewards are only one type of motivation. Read more

Putting the User in User Assistance – WritersUA

People on today’s social web are accustomed to participating in conversations, having a voice, giving opinions, offering reviews, and generally interacting with content and with each other like never before on the web. How can we enable users to respond to or contribute to user assistance? The answer could be a wiki, but a wiki is not required to enable more interaction with users. Here are some specific techniques, starting with the simple and moving towards the more complex, including wiki implementation practices. Read more

What I’m reading

I’m also posting reading items to my delicious.com/annegentle account that might interest my blog readers.

First Steps in Flex Screencasts

The concise examples seem to resonate with how developers learn new technologies.

We meant to do that… (part I) | MsCyra’s Web Development Blog

They say developers learn best by watching (or seeing the results of) other developers code.

How developers learn survey results – interesting

Results from flash developer survey, 100 or so responding. “…the tendency to lean heavily on search to find out about technology and the low number of developers who use classroom training. Online training and videos are fairly popular – although in each case around 50% do not use them.”

WDVL: ‘Users’ Versus People–Understanding What Motivates Online Behavior – Page 2

“As consumers of online experiences are becoming more sophisticated and demanding, understanding and applying psychological and sociological principles in the design of online resources is becoming increasingly critical.”

Documenting Open Source Software

I love reading different community perceptions of both FLOSS Manuals, where we write open docs for open software. I’m also lurking on mailing lists and forums where open source projects are figuring out documentation needs for their users. Forgive me if I ramble a bit, but I’ve been thinking about these concepts lately while discussing them with other writers.

Attention on FLOSS Manuals

Here is a great quote from a recent outburst of articles and blog entries mentioning FLOSS Manuals. On the Linux and Open Source blog on ZDNet, Dana Blankenhorn summarizes his post explaining “Why open source documentation lags” by saying,

If programming is like bicycling, documentation is more like basketball. The best players don’t always win.

He offers great explanations for the lags in documentation, and let me tell you, the reasons are not just tied to open source software, all software documentation could use more team sport and collaboration efforts to create decent documentation.

On Network World in a post titled “Creating a library of FLOSS Manuals,” Amy Vernon asks, “…why do so few applications have manuals to start with?” Her initial answer is tied into the use of manuals, asking her readers, “When’s the last time you read a user manual?” Fortunately, she found the offerings on FLOSS Manuals to be quite useful. And I think that’s the key to software documentation, whether it’s open or closed, the usefulness of the doc no matter what form it takes will be its final measure (such as, distance to be tossed or microseconds spent on the page).

What’s Free and Open Software?

At the STC Summit someone asked me quite earnestly, “But what is FLOSS? What does Free, Libre, Open Source Software mean?” I think she wanted to know, is it a philosophy, a concept, a rubric, a religion? I believe the explanation she sought is available in a question and answer set on the FLOSS Manual’s About page, describing both free and open.

Open Source emphasizes availability of source code to software users. … Free Software emphasizes the freedom to modify and reuse software, which of course also requires that source code be readily available.

I wish I could pull these great quotes out of my back pocket when speaking about FLOSS, but I keep learning myself and integrating the definition more fully in my own mind.

Talking Even More about FLOSS and Docs

Last week I talked to Michael Cote last week about wikis, open source documentation, and so on, for his new “make all” podcast. See Coté’s People Over Process » Beyond Documentation – make all #004. I immediately jumped to “who are you writing for?” as the very first question to ask. I think you also should ask, “What are they reading already?” Audience analysis is important everywhere but even more so in open source I would say, because much documentation effort is focused on the developer, which sometimes means non-technical end users get ignored. Also, there is so much free, liberated content in open source, you have to visit (ans answer!) the question, do we make it or gather it.

I also said that FAQs are a perfectly good starting point, especially if customer support is your main goal. In an email exchange later, we talked about how documentation is a great conversion tool for website visitors. With web analytics, that measurement is possible. In essence, your documentation can be your storefront. Aaron Fulkerson describes it well on the MindTouch Blog, in “Your Most Valuable Storefront.”

Business Etiquette, Community Etiquette

After seeing this great instructional guide to eating sushi, I realized the only way I knew any of the rules or guidelines for sushi dining was through example. I learned that one of my examples was wrong – you’re not supposed to make a “soup” with your wasabi in your soy sauce.

Sushi Rules, Social Media Rules

These sushi instructions remind me how tough it can be to teach social media. I have had a few college professors ask me, what should I be teaching in a social media class, and how will I know if they have the lessons learned that they will need? I have been thinking about this question often.

One answer is, social media is just another tool in the toolkit to help you do your job. So, the same rules apply as in other learning situations. Yet, I think this answer is a copout. Some lessons are harder to learn than others and may be quite public and offer some humiliation. With an online community marching towards a goal, the stakes are higher than whether or not I made a wasabi soup.

In some cases, the situations are as specialized the rules of a golf foursome. Don’t talk or make excessive noise while someone else is concentrating on their swing. But golf has many more detailed rules that you learn as you practice, or rules that apply when it’s hotter than 90 degrees, such as where you can drive a golf cart. Golf insiders know these rules from years of practice and from having someone show them the rules.

So what are some of the rules we should help online community members with?

Understanding Subtleties and Helping with Guidelines

Social media and online community settings have many obvious rules, yet there is also subtlety in many online communities that insiders must explain to others. Guidelines you would find for online communities are basic for any people skill.

  • DON’T TYPE IN ALL CAPS. You sound like you’re shouting! The same sensation can occur with exclamation points!
  • Some communities will have more or less tolerance for people who sell things – be it software or services.
  • Introductions are still important in online communities.
  • Your dress and appearence may not matter as much as in-person meetings, but your online representation of yourself can either look spiffy or slobby.
  • Interruptions are also difficult to judge in an online setting, so you want to go with the normal flow of conversations that you can observe.
  • Make sure community members have the resources and connections they need to do the job. This guideline is basic business etiquette but might be more difficult in an online setting.
  • Know when to switch communication to real-time – whether it’s phone or Skype or IRC, having a good feel for when to talk synchronously is valuable.
  • Understand local cultures and norms, even when participating in a global community. Basically, be considerate of others.
  • Know when to ask questions, how much to research before asking, and figure out where questions are answered.

I know there is much, much more to business etiquette than just these guidelines. What am I missing that is essential for a student of social media to understand before approaching an online community? How should a student conduct themselves online?