Category Archives: wiki

community wiki work writing

Game Changers: Rackspace supporting Girlstart here in Austin

Creative, brave, resilient, these are all words we cherish for our daughters, our best friends, our coworkers, all those who have faced any sort of technical or scientific challenge and wondered if they were up to it. Rackspace sponsored at table at the GirlStart Game Changers Luncheon yesterday and we managed to overflow one table to another. We had a great time!

IMG_0038

Girlstart is an Austin-based organization that offers after-school and summer camps for girls to try science, technology, engineering, and math through fun experiments and solving real problems. We had a great time listening to Mythbuster’s Kari Byron talk about her journey to science ed TV from sculptor to tester of myths. One especially grabbing tale was a test for the smell of fear in a glass coffin trapped with a mass amount of crawling scorpions.

One story of hers that stuck with me was how she got her start with special effects work in the M5 studio, owned by Jamie Hyneman. A friend encouraged her to go see what special effects were all about, thinking there was more money in movie-making artisan work than other starving artist outlets. She was so inspired she went back to put together a portfolio and told him she’d work for free so she could learn as much as possible about making effects and movie props. Well as it turns out, Jamie’s a frugal guy, and definitely got returns on his not-too-much-investment!

IMG_0041

In listening to her story I realized there’s a parallel to my journey to open source. I was interested in “how are wikis really working for technical documentation?” so I offered to work for free on one. Turns out, that volunteer effort launched me into the career I have now, working on a large open source documentation efforts for OpenStack, the open source cloud. I could identify with the need to be brave, creative, empowered, resilient, and all of those are offered to me while working on OpenStack and in open source. How about you, when have you volunteered for work just to learn as much as you could about the work?

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.

Reorganization

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.

Additions

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!

techpubs wiki writing

Must Read: Confluence, Tech Comm, Chocolate

“Who cares about printing money, let’s print chocolate!”

–Chapter 23, Driving Wiki Development, Confluence, Tech Comm, Chocolate

Do you need proof that Sarah Maddox, author of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, is a complete chocolate and wiki expert? Let me tell you, she knew that one day we will print chocolate in our (industrial-grade) kitchens. And sure enough, that day has arrived! And so has her book. It’s a wonderful addition to the XML Press family.

Sarah has an amazing knack to start at the beginning and introduce wikis in a friendly way even though she has been living the wiki life for years. She writes an introduction to wikis in an approachable way and ensures the reader knows the context is technical communication. But for me there are technical details revealed that offer the best chapters of this book. There is the deep technical dive into “building online help” especially her case study of web-based, context-sensitive online help. This solution should rock your world if you’re looking for a cross-platform web delivery of your online help. Her chapter about “a day in the life” of the wiki is just what you need to understand how this delivery and collaboration solution is different from “ordinary” technical writing. And I thoroughly reviewed and enjoyed “Giving your wiki wings.” Wikis with wings are the way technical writers will show their value to the world. I especially appreciate the chapter “Driving wiki development,” where Sarah is clearly honest about gaps in wiki functionality and how we can actually improve our experiences with wikis.

This book is an important, essential addition to the professional writer’s bookshelf. I’ve already whole-heartedly recommended it to an entire team of Rackspace writers and to all my Austin-based writer friends who have listened to me talk about the changes in the industry over the years. I want to recommend it to all of you as well. This book offers both visionary inspiration and the nitty-gritty technical details for all of us working in this web-centric world. I have so much respect for Sarah’s work on this book. Her enthusiasm for the wiki way shines through each page – web page and printed page. Pick up a copy, devour it like a chocolate bar, and drive collaboration for technical content.

Buy now at Barnes and Noble

Buy now at Amazon.com

techpubs wiki writing

Pick a beat for release notes

Journalists at Play Flickr: Lisa PadillaThis is fun. Fedora has “beat writers” which harken to journalists tracking a story. Each beat is a section in the release notes. I found it while poking around on the Fedora wiki pages that describe how they do documentation. See fedoraproject.org/wiki/Documentation_Beats.

I like this approach for a few reasons. One is that the term “beat” seems fresh. While I did have to look for the definition of “beat writer,” I had a notion in the back of my mind and it turned out to be correct. My initial reaction was, oh, it’s like a journalist chasing down a story, or beat reporting, being assigned to a regular route.

The second strength I see in this approach is that you can divide writing tasks and track progress. Having a “beat” assignment also matches knowledge areas to experts in that area.

Assigning someone to a “beat” also means they’ll try to uncover a story. More software documentation could use story telling. Try to tell the stories your users tell you – or better yet, let them tell their story. Curate these from blog entries or chase the story down yourself with interviews.

We’ve probably used this type of approach for ages in enterprise documentation, but this strikes me as a particular good way to parcel out work in a collaborative environment while still maintaining a high quality outcome.People are naturally drawn to their interests, and assigning them writing tasks based on areas of interest is a great method for making community documentation fun and engaging.

wiki writing

Wiki Best Practices from Wikia Content Team

I found this great set of best practices for wikis on the Wikia site. They host 275,000 wiki sites on all sorts of topics, and truly want to help people reach the most potential with their wiki by offering guidance. One of the pages lets admins of a Wikia wiki ask the Content Team for specific help. Here’s a direct quote from that page:

We’d love to help attract new contributors to your wiki. If you’re interested in working with us on optimizing your wiki, we’d like to be sure you’re following a set of best practices.

  • The requester should be either the admin, or link to a discussion with the admin of the wiki and agreeing to skin design and homepage help
  • The wiki should have at least one active admin, meaning he or she has made at least one edit in the last 7 days
  • The wiki should have at least 50 content pages, not counting stubs. Stub articles should make up no more than 1/5th (20%) of all pages on the wiki
  • The wiki should have a clear category structure to help readers navigate around the site. Every content page should be in a category
  • The wiki should not be in the middle of choosing new admins, or any other upheavals. It should be a stable, friendly place
  • The wiki should be using the Wikia welcome tool, signed by admins — (MediaWiki:Welcome-user should say @latest, @sysop or the name of an admin)
  • The wiki should not use offensive language or include inappropriate images.

The Content Team will make all final decisions and design work will be at their discretion. If your wiki meets these criteria, leave a message on the talk page of this article.

The Content Team appears to call this criteria the bare minimum for calling your wiki a wiki, based on activity (must be updated at least weekly) and have at least 50 pages containing real content, not just part of an outline.

What’s interesting to me is that this team realizes that the people are as important as the content. Without consistent people and a proven way to welcome more people, the best practices aren’t met.

Lots of people ask for wiki best practices – these are a broad set for multi-purpose wikis on topics from video games and TV shows to food and fashion. It does offer a bar to reach for any wiki.

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 tools wiki work writing

Observations from the Open Help Conference

I attended the Open Help Conference in lush, green, over-20-inches-of-rain Cincinnati over the weekend and learned so much. I wanted to share my observations in a longer format than the 140 characters I used sporadically during the conference.

First of all, if you want to read through the presentations, we’ve gathered them on the Open Help event page in Slideshare. My presentation was called Sprints and Stacks: Building a Documentation Community. I walked through my experiences ramping up open source documentation for the OpenStack project. I was pretty honest about my expectations going in and the reality that ensued, which you can read about in the notes.

My Giveaways

These points are all made in my talk, but I wanted to share them here as well. Here are some of the surprises I’ve had while working on OpenStack:

  • Publishers want OpenStack content. I feel like I’m in a fight to be an acquisitions editor some days. Everyone wants an OpenStack book, or blog entries about OpenStack to publish on their site.
  • Doc sprint timing must occur with specific releases. Originally I thought I’d just run sprints at the Design Summit twice a year. Now I see that sprints should probably occur just prior to releases.
  • I once thought docs were a good entry point for new contributors. I now sense that it’s really difficult for new people to contribute to the docs, and I also believe that developers should write for developers.
  • Doc contributors need access to people they can interview incessantly. Plus they need access to hardware, big time. Neither are easy to offer now for OpenStack. I recognize this shortfall, yet haven’t solved the problem completely.
  • I am seriously shopping around the idea of holding an OpenStack tweet chat regularly. If you are interested in hosting a regular tweet chat, please let me know.
  • I have been amazed at the quality of content about OpenStack coming from bloggers. I am happily contacting them and incorporating CC-licensed content.

My Takeaways

I felt like I was in such great company. Shaun McCance did a great job recruiting like-minded people who love to share, discuss, and have fun with documentation. We had half-and-half women and men in attendance, and lots of women presenters. This ratio is a big deal to me as I get deeper into open source. Gender balance in open source and technology in general is a difficult sometimes contentious topic, but we’re definitely onto something good with this group. One of my favorite tweets was this one:

‘The number of women in an IT organization is the same as the number of people named “Dave”‘ (quoting @Loquacities (Lana Brindley) #openhelp)

and another great one from @jenzed:

The discussions at #openhelp are much enriched by having participants who are not members of the open source choir.

We had less than thirty people in attendance, but these were “my people.”

XML versus wiki

I have to talk about the dichotomy between using a wiki for community-contributed documentation and using an XML plus version-control system for collaborative authoring. Both methods were well-represented by Red Hat and Mozilla.

One of Red Hat’s 60 technical writers, Lana Brindley, spoke about their awesome XML-based writing workflow in Open Source Documentation in Four Easy Steps (and one slightly more difficult one). They have dedicated editors, a style guide, an IRC channel dedicated to grammar, and a search engine specifically created for writers to find content to reuse, plus a topic-based doc platform that allows writers to put together doc builds, which they built themselves when they realized they didn’t want to build a component CMS. What she described was a very mature and high-quality, yet agile and flexible and open, documentation process. Red Hat rivals any of the large enterprise documentation projects I’ve seen and accomplishes everything an enterprise needs to, yet with open source tooling, standards in XML, and somewhat hacked-together tool chains. Their content is translated to 23 languages, a feat only also accomplished by such companies as Dell, IBM, and Microsoft. Their culture sounds amazing, working for the “good guys” with tales of writers and developers working together to build the needed tool chains. I learned a lot about Publican and translations, about when to keep tweaking and when to release something to the wild.

On the Mozilla side, Janet Swisher presented a talk titled, Engaging developers in Mozilla’s documentation. Their documentation process is tightly coupled with development practices including tracking doc requests in Bugzilla. Considering that they write completely on the wiki-based Mozilla Developer Network, and that they’ve perfected their workflow over years, it seemed like a perfect match. They are also running frequent doc sprints, on their third this year. Their easy-to-use doc tools paired with their high number of page views have created a perfect storm for recruiting contributors and their content. For example, Google’s writers have chosen to put their content that’s not just about Chrome but geared towards Chrome web development on MDN. This gathering sounds like a perfect combination, curation from the creation point. She also included the reasons why people don’t contribute. One, their site is so beautiful and engaging that people don’t see the Edit button (they don’t know it’s a wiki), two, they’ve got “yet another login” syndrome, and they don’t want to bother with setting up an account, or three, they’re too intimidated by the relative “fame” of the original author to change “the” documentation.

Lots of Work

During Dru’s talk about Starting an Open Source Certification Program, I tweeted the following and @Sheppy (Mozilla writer Eric Sheppard) agreed with me.

Great talk from BSD author and community manager Dru Lavigne about certification programs at #openhelp. Wow just wow, the amount of work.

We’re in the early investigation stages of certification on OpenStack and we have a long road ahead of us. From the number of surveys to psychometricians ( had to look that one up) to collaborative exam design, open source certification is a unique program to run. Exam delivery and Angoff sessions were new concepts to me. Exam delivery has been an ongoing, six-years-in-the-making, process for BSD. Six years gives you pause. These groups are serious about certification and it shows. Fortunately we’ve hired Belinda Lopez who can navigate these areas and knows how to engage the community.

On the second day, we discussed language and localization and I learned that I can export our DocBook files to po for translators to fit into their workflow quite readily. You do have to be strict about freezing the English version, most likely, or you’ll have widely out of sync documents. Since I have two types of source files already, both RST and DocBook, I’m not certain about freezing the English version just yet. Perhaps after some reference configurations are available and documented and I get more hypervisor docs, we can look into translations. Lots of respect in the room for the project managers of translation projects in open source.

We also had a great discussion about recruiting writers and the difficulty in choosing channels for communication – go where your people are, or branch out to lots of social media sites? We had one of the Mozilla writers who has now participated in two doc sprints say that he found out about the doc sprint by searching for free t-shirts on Twitter. So he was a shining example of finding recruits through lots of channels, not just on your classics for your project. To me, this shows you that social media and tech comm have a connection and outreach and community support are upward trends. Jennifer Zickerman’s talk, Coordinating Documentation and Support: Turning Complaints into Contributions, was outright inspirational. Thunderbird has 10 employees, 50 contributors, and over 10 million users. These numbers are mindboggling, yet they manage and thrive. I tweeted,

Seriously cool way to create a support community with Twitter – see the Army of Awesome at http://bit.ly/mRty7U #openhelp

I’m very impressed with Mozilla, an organization that’s willing to take the negativity in some tweets and turn it into altruistic goodness and pay-it-forward attitudes with the Army of Awesome. These cutting-edge techniques are what we all should look for in open source projects. They get the job done with what they have because they are driven to help.

I relish the work ahead, and I so pleased to have the opportunity to work on open source docs with OpenStack. We had a great time at Open Help, and Scott Nesbitt has a nice write-up and links to each presentation on his post, Looking back at the Open Help conference. We’re all hoping Shaun has the energy to put one together again next year!

wiki work

Working at Rackspace with OpenStack

I’m finishing up my first partial week as a “Racker” – that’s what employees at Rackspace are called. I’m a special sort of a racker, a stacker, because I’ve joined the OpenStack team as the OpenStack Technical Writer. My wiki apprenticeship and open source documentation experiences with FLOSS Manuals gave me great training for this new role. I’m extremely grateful to get this opportunity.

My first day orientation was great – we got great stories of the startup days, met interesting, passionate Rackers, and toured the facility that is a re-claimed 1.2 million square feet mall (we’re only using 200K of that space in an old Mervyn’s). There’s even the world’s largest word search plastered onto the wall. It’s tough to solve while riding on an escalator.

As I talked to Rackers, I was constantly reminded of my recent read of Tony Hsieh’s book, Delivering Happiness. Apparently it’s on the book club list at Rackspace but I’d say they are already a textbook case study with their fanatical support.

As it turns out, Sarah O’Keefe’s post asking if “all your followers are belong to us” asked some appropriate questions related to my experience, starting as a new employee. While there is no official blogging policy at Rackspace (yep, I asked), I was asked to write my introductory post shortly after accepting the offer, and Content Stacker, Reporting for Duty is the result. Here are the first couple of paragraphs:

Well, hi there. Glad you could make it. Let me introduce myself. I’m Anne Gentle, the newest addition to the hardworking OpenStack team. And I’m so eager to get started I can barely contain myself. I’ve been in lurker mode for a few weeks and now it’s time to reveal my role – I’m the OpenStack Technical Writer.

How did I get here? I first started working in open source a few years ago, and I applied my technical communication skills gladly because there is often a gap in documentation and support in open source projects. I became a big supporter of FLOSS Manuals, where we write free manuals for free software. We work in a wiki and in Booki, a new collaborative authoring platform. We also employ a book sprint technique where we focus collaborative authoring efforts into week-long sprints. I’ve helped with a few book sprints and think it’s a great technique for open documentation.

Where do I go from here? Today I want to start outlining some documentation strategy to get your feedback and tweak it. We’ll be testing doc efforts as we go and likely start with the Object Storage area. Read more

If you think it’s intimidating staring at the blank “page” on your computer screen, imagine my quaking insides this week as I stare at the freshest new wiki I’ve ever faced – wiki.openstack.org. I’ve got a strategy started that I outlined in my introductory post, and executing it with this community is going to be the fun part.

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?