Tag Archives: community

community techpubs work writing

Book Sprint for OpenStack Security Guide

The legendary book sprint method has come through again! This past week in a bunker, I mean, secure location near Annapolis, a team of security experts got together to write the OpenStack Security Guide. I’m pleased as can be to have the privilege of sharing the epub with you here and now, the evening of the fifth day!

Download the epub file and start reading. One of the goals for this book is to bring together interested members to capture their collective knowledge and give it back to the OpenStack community.

This cover gives you a glimpse of the amazing feat this team pulled off. We’ll have HTML and PDF in the next couple of weeks to fulfill your multi-output consumption wants and needs. For now, fire up your ereader, and start reading! The team wants your input.

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 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!

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.

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.

Trends and Open Source Writing

I get the greatest emails sometimes, thanks to my blog. Here’s the lead-in line that especially piqued my interest:

“I’m researching trends in technical communication for a grad-level writing class,”

She had me at trends in technical communication. And research. So of course, I read on.

” and I’ve found lots of posts on the web by established tech writers who specialize in the open source arena and who appear to be fairly entrenched in technical industries. Any references to the wanna-be writers in the same environment are followed by quips about their being poor, because they have to do a lot of jobs gratis to make a name for themselves.”

At the time I received this note, I had just started in my role as a technical writer and community doc coordinator for OpenStack, open source cloud computing software. I was surprised by the juxtaposition she noticed just in researching web posts, so I read on.

“Maybe I’m making the wrong inference, but it also seems that the comments about new writers are referring to grads who fit the traditional model of the 22 to 25-year-old coming right out of college. For my essay, I’d like to talk about the trends in Open Source where the “new” writer is middle-aged, possibly even retired, with years of expertise in a non-techie industry.”

Wow, I thought. A thesis about Open Source writers. I remember riding with Janet Swisher from Austin to Dallas for last year’s (2010) STC Summit, and we could count on both our hands the number of Open Source writers we know. This is a small group to study but a fascinating group in which to look for trends. Plus, I’m in a position to recruit writers who want to write for Open Source projects.

“Based on your experience, do you see an emerging need for writers (we’re talking paid gigs) who have lots of expertise in other areas, but are looking to switch to tech writing for their next career or as a part-time job in retirement? What avenues would be best to explore in the start-up phase?”

This thesis could help me understand this small group, so I responded and encouraged others to do so. But. I was left with trying to decide if I agree or disagree with her thesis, that Open Source attracts retired writers with years of expertise in a non-techie industry. I wanted to sift through which points I disagree with.

1. Age or years of experience in Open Source writers: The tech writers who are established in open source are often highly technical but not necessarily in a certain age group. I would say their technical skill set is the thing they have in common. I honestly haven’t met an early-20-something open source writer yet, come to think of it. I think you have a lot of work to do to “prove” yourself when coming to many open source projects as a volunteer. There’s a lot of meritocracy where only your work matters, not your methods necessarily. Here’s an example of what I’m talking about. Open source projects often use wikis (extremely lightweight CMSes) for documentation. Experienced, entrenched-in-the-enterprise writers are surprised at how effective a wiki can be for authoring and delivery, especially when they’re used to an Adobe toolkit. So, from where I sit, I don’t currently see “a trend in Open Source where the “new” writer is middle-aged, possibly even retired, with years of expertise in a non-techie industry.” Also, writers in open source nearly always come from technical industries.

2. Having to take lots of jobs gratis to build a reputation: Yes, you would have to do some jobs for free to make a name for yourself, but I’m doubtful that new tech writers have the experience needed to be a huge contributor or lone writer on an open source project. I say that because I have talked to college students (more than 10) about helping with FLOSS Manuals work or with OpenStack and I haven’t seen big contributions from any of them, yet. I’ve also invited college students to book sprints with little response. College graduates are another story, but I have no experience with recent grads to speak of, so I don’t have even anecdotal data to share.

3. Emerging needs for open source tech writers?: I definitely don’t see an emerging need for “new” writers looking to switch to tech writing or part-time in retirement to seek out an Open Source writing gig. That said, through FLOSS Manuals I have definitely met and worked with seasoned (but not retired) publishers and writers who have great contributions writing, testing, and publishing pages and pages of information. These weren’t paid gigs, although these volunteer opportunities certainly lead to great opportunities

These are just my observations in less than five years participating in open source communities. How have your observations differed?

Open Help Conference, Cincinnati, OH June 3-5, 2011If you’re interested in open source and documentation, please take a look at the upcoming Open Help Conference coming up June 3-5, 2011 in Cincinnati, Ohio. I’m the new kid on the block, embracing these techniques (maybe hugging them too hard?), looking forward to learning a lot and sharing my experiences. I hope you’ll join us!

techpubs tools

Open Help is Open

The tech writers who are established, recognized figures in open source you can probably count on your fingers and toes. About two years ago they gathered for the Writing Open Source conference, hosted by Emma Jane Hogbin. I couldn’t attend myself – it was the year of the pinata bat incident. But the group of people who were there are passionate about open source and documenting it. Shaun McCance, the GNOME doc team leader (fearless at that), has gathered a program committee of sorts to start a new conference, built on the energy and connectivity at Writing Open Source, called Open Help.

Open Help! I’m immersed in it daily now, coordinating OpenStack documentation. Open Help embraces all the people and systems that enable us to do amazing things with open source software. Open Help promotes open, transparent techniques for documentation and support, whether through community-based techniques, open source culture, corporate and enterprise settings. Open Help is both Open and Helpful! What more can we ask of our community documentation and support efforts than these two things? But how do you commit to openness and deliver on that promise? We all want to talk to each other about that and share experiences.

Scheduled for June 3 to 5, 2011, this conference will bring together the leads and supporting actors for successful open source projects. We will share ideas, best practices, success stories, and working systems that all of us can use to create and manage the best Open Help possible.

Open Help Conference, Cincinnati, OH June 3-5, 2011

Conference Format

Just like Open Help is not your parent’s help system, the Open Help Conference is not your parent’s conference. We want to encourage as much engagement and interaction as possible while still providing learning and sharing opportunities. How? By combining the best elements of traditional conferences, camps, and unconferences.

Conference Schedule

Held over a weekend, the intent is for people to pop in for as long as they can while also encouraging project sprints or retreats following the weekend.

Attendees

We’re not simply inviting conference participants, we’re encouraging activators to join us in Cincinnati in June. As those who work as community members on open source projects can attest, you get more out of open source when you really connect with the vision for the project. We’re encouraging those who share a vision of better user experience, accurate and connected documentation, and top-notch responsive customer support to participate. Registration is now open for just $80, and will go up to $100 at the end of February.

Opportunities

This event’s success depends largely on participation and sponsorship, so we invite everyone to get involved in some way.

We want to encourage participation and interaction with our supporters. Ideally, a sponsor will send a group of people to participate. There’s real value in the connections and sharing that will happen in-person at the event. Contact me for more information about becoming a sponsor.

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.