Category Archives: content strategy

community content strategy techpubs tools

A Few of my Favorite Things for 2013

tumblr_m8lsqnjijt1qgx2ojo4_250

This year has been filled with interesting finds, discoveries, and productivity. Plus oxford commas! Here are my favorite things for 2013.

The Hunger Games trilogy, because it’s like a window into a mind of a smart writer who writes with purpose.

The Documentation chapter of the Developer Support Handbook has to be one of my very favorite things I discovered this year. I’m on the Developer Relations Group team at Rackspace and this is a great handbook for all of our team.

Animated GIFs, pronounced jifs, am I right? OpenStack Reactions cracks me up.


Grace Hopper Conference by the Anita Borg Institute, especially the Open Source day, and the GNOME Outreach Program for Women which OpenStack started participating in this year. Women in technology are my favorite!

The Houzz App on my Android tablet for eye candy while messy remodeling was actually happening. Plus it’s the best content remix site I’ve seen in a while, more targeted than Pinterest.

Photo kids

Probably the best photo of my kids this year, I make it a favorite because at their ages it’s difficult to get one of the both of them.

OpenStack Docs Boot Camp

OpenStack Security Guide book sprint, read it at http://docs.openstack.org/sec/.

oreilly-openstack-ops-guide

OpenStack Operations Guide book sprint, now an O’Reilly edition, read it at http://docs.openstack.org/ops/.

How about you? What are some of your favorite things from this past year?

content strategy techpubs tools writing

Documentation as Conversation with CSS

Three types of speech balloons: speech, thought, scream.

I love to explore new ways of conveying technical information, and I’m interested in documentation as conversation. Last year I wanted to convey a “side note” on each page of a Sphinx site, as if the page were talking to you. I needed to let people know that there are additional documentation pages available. So, I went looking for a CSS design that would let me put the note into a particular tag and style as I like. I found it at Pure CSS speech bubbles. The humorous part was figuring out what speech bubbles are also called so I could do a Google search. Speech balloons? Dialog balloons? Word balloons? I never did come up with balloon but somehow found bubble.

For Sphinx sites, which are built from RST (ReStructuredText), you use a layout.html file in a _theme folder with your .rst source files. This templating is explained in more detail on the Sphinx documentation site at http://sphinx-doc.org/. In this case, the p tag is styled with css classes. Here’s what the HTML looks like:

<p class="triangle-border right">
Psst... hey. You're reading the latest content, 
but it's for the Block Storage project only. 
You can read <a href="http://docs.openstack.org">
all OpenStack docs</a> too.</p>

The CSS is much more involved, giving borders and rounded edges and putting that little triangle to indicate the speech. You can see it embedded in the Sphinx framework at tweaks.css. You can select a border color to match the rest of your page. Here’s the resulting HTML output. Speech bubble example

You may have seen the trend towards comic books or comics to explain technical topics, such as the one for Google Chrome at http://www.google.com/googlebooks/chrome/. There are drawn comic characters explaining the browser design considerations throughout, with speech bubbles, hand waving, folded arms, lots of body language expressed throughout. This simple side bar doesn’t attempt that level of engaging content, but it’s a playful way to let people know there’s more than a single page for OpenStack docs. What do you think about such techniques, are they playful and harmless or sloppy and annoying?

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?