Category Archives: social media

Why use GitHub as a Content Management System?

GitHub is a website that gives a user interface to source control. The tagline on the site is “Social Coding,” and I find that phrase to be an excellent summary of why GitHub is so useful for collaborative documentation. When writing for developers, write with developers, and believe me, developers are using GitHub for writing and coding. Like many tools, git and GitHub were created by fire—through a pressing need in 2005 for high-throughput and efficient source control management for the Linux kernel.

GitHub is the web interface, and git is the command-line tool that you use to copy files locally and track them. It’s cross-platform, so it works on Windows, Mac, and Linux operating systems. The biggest difference between git and other source control systems is that it merges files with a best guess rather than a “lock and checkout” model. The best guess for merging is often accurate but does require human inspection when the changes are too close to tell. The non-linear branching model means that you can experiment with many changes but still get back to a known state.

Here’s a brief vocabulary list for GitHub.

  • A repository is a collection of stored code or source documentation. For example, openstack-manuals.
  • A branch is an indicator of divergence from base. For example, the stable/liberty branch of openstack-manuals.
  • A commit is a point-in-time snapshot of a repository with changes. For example, this typo commit.
  • A fork is both an action and an object: forking is when you copy a repository, and a fork is a copy of a repository.
  • An issue in GitHub is a way to report defects, tasks, or feature requests. For example, an install article issue.
  • An organization in GitHub is a collection of repositories. For example, Rackerlabs contains Rackspace repos.
  • A pull request is a comparison of edits to see if the reviewing team wants to accept those changes into the main repository. For example, this pull request for a Rackspace page on

GitHub has some offerings that cover a couple of different use cases. Private repositories on the public site are about $7/month as a subscription and let you mark a repository as private and only invite trusted collaborators. GitHub also has an enterprise offering where the entire website is hosted where you want it and branded with your domain name. With GitHub Enterprise, you can ensure only company employees can access the source and collaborate with each other. Look up more options and pricing information on

Why use GitHub instead of a traditional CMS for docs?

When you are collaborating with technical people on distributed projects, often they are already accustomed to a GitHub workflow. So applying that workflow to technical documentation related to the project is a natural fit. Also, since GitHub has flexible review processes and prioritizes continuous integration, applying those benefits to documentation reviews and builds gives you the benefit of content management while bridging to sharing knowledge with subject matter experts. GitHub is a great match for when developers are writing documentation in source control. GitHub works well when a project is so large or distributed that no one person can know enough to write the documentation for the project. While GitHub is often associated with source control, the collaborative aspects go well beyond the traditional source control and CMS models.

In OpenStack, we have documentation workflows that mimic our code collaboration. We post patches for people to review, we review each other’s patches (similar to a pull request on GitHub), and we have build and test automation for every doc patch. The idea is to use the collaboration available in the GitHub pull request workflow for docs as well as code. We’re all responsible for relevant and accurate documentation for about 25 OpenStack projects written in Python across 130 git repositories, so let’s work together.

I do get questions from writers who are getting started with these types of workflows, so I wanted to bring together some of the best practices we’ve found, and find more. Here are two articles that serve the purpose along with a slide deck from a presentation I gave this year.

What’s New in Conversation and Community?

Conversation and Community 2nd Edition Cover

Love this new cover, both photos are Creative Commons licensed once again. Let’s look between the covers though!

While thinking about the second edition and how three years had passed, I was pleasantly surprised that we could get to the three year mark with the book’s content remaining relevant and accurate. Seems nearly impossible on such a fast-moving topic as the social web. Yet while looking through the tools chapter to update it, we mostly tested URLs and looked at the categories. Surprise, nearly all example tools are still relevant and useful to technical documentation. Not all the exact examples still existed, but that was just interesting to revisit.

Next, I examined the book for three areas of improvement – organization, content updates and additions based on my most recent experiments and experiences with OpenStack at Rackspace.


With the tools being so much more a part of every  day life and work now, I have moved the “Concepts and Tools of the Social Web” chapter to become an appendix. It also lets readers go right into “Defining a Writer’s Role with the Social Web” where I walk through a strategic approach to the social web. I also moved an entire section about managing community methods into a new chapter titled “Analyzing and Measuring Web Techniques” to expand on the management practices and business value tie-ins.


Some of the best additions to the book are interviews with practitioners I’ve met over the years who are doing community-based documentation already. It’s a balanced mix of open source communities and corporations using community to add value to their offerings. These are scattered throughout the book. I answered these same questions as well about how my current work is structured.

Based on my observations with documentation comments over the last year and a half, I added plenty of commentary and guidance to “Commenting and Connecting with Users.” Selecting and implementing a commenting system is chockful of requirements and guardrails for comments included on every page of your documentation. I also give an example of how to process comments daily, weekly, and moderate comments.

I added some additional information to the wikis chapter based on my recent experience with a Google Summer of Code documentation summit, comparing and contrasting “typical” wiki writing to planned writing. Many wikis have become web content management systems that encourage collaboration, so while I continue to address wikis in a separate chapter, the community and conversation building remains at the heart of my book. For wiki-specific tactics using Confluence, I’d highly recommend Sarah Maddox’s book, Confluence, Tech Comm, Chocolate, which I reviewed previously.

I added a chapter about content strategy for community documentation. I’m definitely sensing a strategic specialty opening up right now, and want to keep exploring it through the lens of content strategy. There’s a great case study included as well about Autodesk and their learning communities. An interview with Victor Solano with Scot Abel lets you “explore how the software giant has leveraged the power of the crowd, software standards, and content management to meet the fast-changing needs of its customers.” I found it thought-provoking and inspiring.

If anyone would like a signed first edition, please let me know by sending an email to annegentle at justwriteclick dot com. We’ll work out shipping and payment (Paypal or check-in-the-mail) with the few remaining copies I have!

Choose Conversation and Community

We’re closing in on the second edition of my book being released and available! I’m super excited about it. I can’t stop thinking about it. On the way back from the O’Reilly Open Source Convention, I started doodling in a new notebook when all “items with an on/off switch” had to be off, and came up with this diagram for what the social web means to me.

The terms social relevance, social networking, and social media, as a triad for explaining the social web became very clear to me after reading this rather complex title: Enterprise Social Technology: Helping organizations harness the power of Social Media Social Networking Social Relevance by Scott Klososky.

Social Web

You see, these three social powers offer us content folks an entry to the strategic playing field of the social web.

What I realized is that there’s a stream of conversation and community throughout all these social threads. I hope that the second edition of my book connects these threads with more clarity than ever. I hope the long title doesn’t prevent you from tweeting about it. And I hope we all can relate our stories to each other to keep learning about the social web and growing our field’s influence on it. Let’s choose conversation and community as a strategic benefit to all our documentation efforts.

Facebook for Social Support? I like.

When we first rolled out TryStack, a place for trying out cloud! for OpenStack, we heard the groans from the audience since our first ID check is through a Facebook login. No Facebook, no TryStack. But since we’ve worked through the manual process and put a straight-through “Login using Facebook” link on the Dashboard, I have to say the process is super easy and repeatably so.

And I’m quite glad that we have the TryStack Facebook group for people to ask questions specific to TryStack. As the OpenStack doc coordinator I’ve found the group to be very valuable in telling me what information they’re missing, where they get confused about usage, and so on.

I especially like the video linking I can do in Facebook comments. Here’s a link to a video I made introducing people to TryStack.

Best Twitter Account Idea Yet from The Information

You know how all these bizarre yet entertaining Twitter accounts keep popping up? The character-based Mad Men account, @BettyDraper the one quoting his hilarious father (with the not-censored four-letter-word-in-the-title), the FakeSteveJobs account, and how about this insane spam one, @horse_ebooks, told in the Ballad of @Horse_ebooks? Best quote in that article, “The reason it hasn’t been shut down yet is the same reason it’s so hilariously terrible at its job: It doesn’t bother anyone who doesn’t want to be bothered.” I’m sure I don’t have to tell at least half of my readers about the Fake AP style book Twitter parody account. It’s sheer awesomeness.

I have a new fake Twitter account idea. It’s inspired from The Information: A History, A Theory, A Flood
by James Gleick, describing the era of the telegraph, where you were charged by the character. Yet people still wanted a sense of efficiency and value from their telegraph messages.

How about this entertaining Twitter account idea – a Twitter account entirely written in a code that you need an old telegraph code book in order to understand?

Apparently people in the 1880s wanted to be sure the receiver of the message understands manners and respect. One of the subtitles of “Bloomer’s Commercial Cryptograph” states “By the use of this work, business communications of whatever nature may be telegraphed with secrecy and economy.”

Bloomer's Commercial Cryptograph

This book, Arnold’s Telegraph Codes, ensures the use of “Yes sir” and “No sir” throughout.

Arnold's Telegraph Codes

It would be a fun cipher each day or week, to figure out the contents of the message. Pretty sure it wouldn’t be guaranteed to be secret nor economic, but I bet we could ensure the use of Yes, sir, and No, sir.

Yes, these are the sorts of ideas I have about Twitter after using it for five years. What’s fun to me? Ciphers, information, history, and Twitter.

Exciting Future for Collaborative Printed Electronic Books

The future of the book is in your hands from Sourcefabric on Vimeo.

Sourcefabric builds open source software to support independent media worldwide. On February 14th, we’ll announce our tool to help people and organisations write and publish great multi-platform books.

Write and publish great books ready for iPad, Kindle, Nook or print within minutes. Write, translate or reuse content by yourself or with others and let the platform take care of structure, formatting, licensing, versions and export to book formatted pdf, epub, odt or html.

Share, reuse and remix content, chapters or even entire books. For example, import an epub from Gutenberg or a colleague’s textbook, rework and then publish to, or another bookmaking community!

February 14th 2012. The next chapter in publishing.

Google Summer of Code Doc Summit Stories

On my way to the airport after an intense and enjoyable three day session with four open source projects writing a book apiece, I wonder if I have any more words to write down. The group I worked with had 14,000 words in the system by day two. I feel I need to try to capture this experience. I’m feeling a little badly about coming home early – they are still working hard at it today!

The four projects were KDE, OpenStreetMap, OpenMRS, and Sahana. Each project brought 3-5 participants. Some of the participants didn’t know they had applied to write a book in three days. One project already had a long outline, reviewed by other community members. The participants’ backgrounds varied widely – tall, wide Python developers with long hair in a ponytail, disaster managers with cropped hair and glasses, a geology professional with a travel bug, cycling data wranglers and web developers, C++ developers and young gamers, a user advocate who also happened to be a grandma, and then there were the doc aficionados who find all of this quite fun, like me.

We all started the week with an unconference led by Alan Gunner from Aspirations technology, who has a way with words and a distinct gift for engagement. No one hid behind their laptops (though sneaking a peak at a small screen like a mobile phone did happen sometimes). About thirty of us were gathered, and I feel I’m leaving with a sense we have built a community of practice, that I can contact any other attendee to talk docs. What a valuable gift from Google, whose Open Source group funded the week with lodging and food provided.

Story telling

People were quite transfixed by the idea that a book can tell stories. Part of uncovering a story to tell involves audience discovery. FLOSS Manuals community members like Janet Swisher led the teams through an audience analysis exercise. These were her questions:

  • Who is using your tool?
  • Why do they use your tool?
  • What kinds of things are they trying to do?
  • What can you assume they know?
  • What do they probably not know when they approach your tool?

For these exercises, free agents like myself were assigned to one of the four teams. I went to the Open MRS team, which provides medical record software for developing countries. This was a great chance to learn how open source affects human lives. I learned how important it is to know who is setting up their software and why. Turns out, the majority of the project’s communication is with people who want to build a module for OpenMRS in their specialty domain. There are also implementers who want to use OpenMRS as a data store, turning their paper input forms into a form the registration desk can use when a patient reaches the front of the line at the clinic. They’ve also recently seen an uptick in requests to integrate with the OpenMRS platform, such as inquiries from Doctors Without Borders.

Parts of answering the “who” question also led to answering the “why” question – they use the tool because they need some extension of clinical functionality, they need a customization for a particular strain of drug-resistant tuberculosis, or possibly just because “their boss told them to” which then leads to investigation of why their boss wants to use OpenMRS. Mobile data entry and data retrieval as well as language support were parts of the reasons why they’d choose OpenMRS. Some of the stories that came out were not yet well-articulated, but discussing real people with real work was a huge help. I envisioned implementers taking an input form and making an online form, studying the data model while they did so. I heard about patients not making appointments but waiting in line for hours at a registration desk where they would be received for an observation by a medical professional, I wondered about the person accepting shipment of boxes of medicine. These every day tasks capture your attention and hopefully can be translated into a better, more engaging read.

Wiki writing vs. Book writing

On the morning of our third day together, one of the participants made a fascinating observation about the process of writing a book – that he actually approached the act of writing differently this week, with more focus on completion and quality, since he wasn’t writing in a wiki. In a wiki, he expected to be able to write in an outline, freeform, and someone would come behind him, he assumed, and make the text better. But knowing that the final deliverable was looming at the end of the week, he wrote more carefully with an audience in mind when he wrote in the FLOSS Manuals booki tool. This single observation captured my attention. How many others feel this same way when they contribute to your project’s wiki? I tend to avoid that problem by strictly stating what information goes into the wiki, in hopes of also focusing better writing attention in other areas, I guess. But what about writing for a linear, printed book, versus writing for a website where every page could be the first page? I believe us practiced pros know we can improve upon the classic act of writing by writing for personas and telling stories both for a book deliverable or an engaging user experience on a website. But it is certainly a tough task to coach others to do so. I felt that the book sprint experience, compressed and yet with elongated days of intense collaboration, was a great method for coaching improved writing in others.

Result: Books

Three of the four books are now available on Lulu. The covers look fantastic! Congrats to all the authors and many thanks to Adam Hyde of FLOSS Manuals, the Google Open Source Programs office, and everyone who took the time to make these books shine.

OpenStreetMap Sahana Eden

KDE Guide


Social Support and Documentation Communities

Stories of Social Media Sticking in Unlikely Places
Saying, “No one reads the manual” just doesn’t hold water any more. Social technology has intersected even the classic user manual. There’s always someone who will read a book. But their true motivation may be a desire to become an expert on a forum or on Twitter, building an expert’s reputation or reciprocating assistance because they know they can rely on the social web to pay it forward.

The way to amplify knowledge is through social media, social networking, and social relevance tools, gathering a wider audience and working in an economy whose payment is in links and more links. To find a fix for a problem with a cell phone, some chose to go to the phone’s web site and download a manual. Others naturally search on YouTube for troubleshooting hints.

Social media for troubleshooting, training, or trying software or gadgets? Sure. Does this scenario sound familiar?

“The darn thing won’t sync up again,” she grumbled as she tried to unload the latest running data from a sensor in her shoe. The data should travel from the shoe to the iTunes software through her iPod which was connected to her computer so that the data would be uploaded to a third-party website. As you might guess, her first troubleshooting attempt started with the error message within iTunes itself, but after seeing a message from iTunes that told her to reboot the router, she instead opened up a browser window. Without even opening a new window, she searched on Google in a browser plugin. A helpful community posting from a year ago helped her get the data about her five mile run from her shoe to the website.

Google is a new entry point to every help system that is, well, helpful. From Google users can view videos, download PDF files of the manual, and read forum posts from people who have come across this problem before. Sometimes Google links go directly to a company’s set of manuals, but more often than not, Google is the entry point to user-generated or community-collected content from blogs, forums, or wikis.

Bloggers who build a reputation as an expert in Adobe products can now be found even more easily with the Community Help search tool, which is a curated collection of blogs, video tutorial sites, and other social media-centered sites. Searching within the Community Help on keywords such as “footnotes” offers up a list of links to Indesign experts who maintain blogs and offer how-to tips and advice.

If people are listening on Twitter to come to other user’s aid, even microblogging and instant messaging applies to the new aggregate troubleshooting guide. Social support communities crop up when social media tools are used to collect questions and answer them or point people on the social network to others who can answer their questions.

Documentation communities are built upon content systems such as wikis that lower the barrier to contribution by giving any page an Edit button. Rather than waiting for a long publishing process to finish, readers can be come authors and editors at the click of a button. And the publishing system itself notifies users when new content is brought on board.

Social and community techniques are a sensation everywhere, even for the boring, unsexy systems applied to customer support and technical documentation. You’ll be glad for it the next time your favorite portable gadget does an unfamiliar flip flop.

Twitter’s Value to Technical Communication

Some responses to an inquiry I got via email from a student at the University of Minnesota in the Scientific and Technical Communication program. Thanks Mary, for asking nice thought-provoking questions!

1. What do you think is the value of Twitter compared to other forms of communication?

To me, the value of Twitter is that it was built based on the patterns some people saw of the ways people were really communicating online – In this interview with Noah Glass, one of Twitter’s founders, a journalist learns that Noah was reading myspace postings and figuring out that asynchronous, status-like updates were how people were really talking to each other online. The value of Twitter that I see after reading that article is that Twitter modeled itself after reality. It works well with mobile devices, a communication device that needed to fill a void in 2006-7. It’s hard to compare it to email or texting or instant messaging, when it’s a messaging system we didn’t know we needed until we had it. Recognizing and filling that need is how Twitter is thriving today.

2. Can Twitter really be used for documentation and if so, what are its unique qualities?

Sure, people are using Twitter for posting tips and tricks and encouraging others to do the same. It’s also being used for Twitter chats, periods of time set aside to talk on Twitter with a particular hashtag collecting and aggregating all the tweets within the time period. Tweets with a certain hashtag can also be displayed alongside online content that serves as documentation. Twitter can be used for the goals met with traditional documentation when the goals are customer support or service, engagement, adoption, research and feedback loops, and other similar customer-serving goals that doc fulfills. So yes, Twitter can be used for documentation, when documentation’s goals align with some Twitter use cases.

3. Are there any accessibility problems facing Twitter and what are the best ways to make Twitter more accessible?

Accessibility improvements usually apply to vision impairment, and the popularity of the iPhone or other smart phones that automatically eliminate most vision-impaired users mean that Twitter is not easily accessible to those usually served by accommodations such as screen readers. I don’t have real suggestions to make Twitter web content more accessible – I actually believe the mobile devices need to become more accessible to vision-impaired people. Touchscreens just aren’t going to cut it.

What’s more interesting to me are the articles about how much social media like Twitter suffers from a “club” problem – it can amplify how disconnected we are with other cultures. For example, when some BET award show topics started trending and some people on Twitter commented as if to say “I didn’t realize ‘they’ were here” I was mortified as were others. That lack of vision and close-mindedness is a huge social problem that social media can amplify. Also, there’s an often hidden advantage that doesn’t have to do with disabilities necessarily. Those of us with fairly “boring” lives (no horrid exes, no fear of violence or retaliation, no fear of identity theft or libelous charges) can use Twitter or other social platforms without fear, but others who grew up in gangs, had to reinvent themselves to avoid prosecution, or people who are chased by violent family members cannot use Twitter unless they’re willing to take much more risk than others.

Learn about Leveraging the Social Web for Customer Support

The webinar and interview we recorded last week thanks to MindTouch is now available for your listening and viewing pleasure. I had a blast talking to Scott. I thought we might argue a bit on some of the points, but we were in much vehement agreement that day! It’s just over an hour long.

video platformvideo managementvideo solutionsvideo player

After the webinar, I answered a few questions on Twitter that were interesting and we didn’t get time to discuss during the hour. I liked this one from @bmdesignhki, Asko Kauppi:

How about making LESS documentation, by having customers scrap out the unnecessary parts. Who likes documentation?

My response was:

Love the question about making LESS docs – I think web analytics will let us be ruthless in our deletions! 🙂

I am still ruminating on this a bit, though. How can we enable our customers to be ruthless about deleting the documentation on a site? We’ve carefully crafted this content, might even have a strong feeling about it, even (gasp) ownership! A customer won’t have this difficulty letting go of the words, so to speak. But if the analytics say it’s gotta go, it’s gotta go. Nearly all the web analytics work I’m doing right now is tightly access controlled. We can send reports to the community, but I don’t know if I’d want the community to do my deletions. Especially if one of the community members was prone to say “Who likes documentation?” Hee hee. Not sure about crowd-sourced deletions, but it does seem like it’s a great job for a fresh cleanup crew. Maybe instead of Earth Day clean ups, we need more Content Day clean ups. Definitely got me thinking more about clean lines and clean docs.

Another question that came through on Twitter was from @djtowne, DJ Town, she asked:

What metrics should social support sites provide?

My response was definitely truncated as 140 characters is hardly enough to respond within, but I said:

re: social support metrics: new v. return visits, time on site, what are they searching for? Comment response metrics for sure.

The longer answer is contained in this post, Web Analytics for Technical Documentation Sites. I have more ideas as well but I’m doing some research with my own OpenStack community documentation to test out some theories. Until I blog again, enjoy the webinar.