Tag Archives: collaboration

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

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.

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

Why You Might Care about the Cloud

Talk about clouds, hybrid clouds, private clouds, and suddenly throw in software as a service and platform as a service, and you might be wondering, what does it mean? Whoa double rainbow, as some would say.

I wanted to put some perspective on the cloud for technical communicators. I’ve had a great guest blogger post from Ynema Mangum about cloud computing in the past titled, Clearing the Air on Cloud, but when I saw Ellis Pratt tweet about using the cloud for one of his projects, I followed up with him to learn more. Here’s an interview with Ellis Pratt of Cherryleaf about his recent experiences with cloud computing.

Q1: Could you describe the project when you recently used a cloud computing environment?

We’ve created a report publishing system, based on Confluence for a client. The reports are fire risk assessment reports, so they want the ability to complete the reports “on the road”.

Q2. What compelled you (or required) the use of virtual computers available on a network for the project?

We put a version of the prototype in the cloud for a number of reasons:

  • The client’s IT person hasn’t yet installed Confluence on their Virtual Private Network (VPN), so to keep the project rolling along, we created a version in the cloud that they could access and review the prototype of the system.
  • We’d also outlined in our proposal how they could host the system in the cloud instead of on their VPN, so it gave us the opportunity to show them what it would mean for the report writers.
  • Our own VPN can be slow at time and holds sensitive data, so it was an excuse to test out the potential of a hosted application server for our own use.
  • There may be cases in the future where clients would want to access a documentation solution hosted by us, so we wanted to research the possibilities and potential.

It was prompted by:

  • A chat I had at a 4Networking (business networking) meeting with a software developer, who said how cheap it was to create a application server these days. We’d looked at it about 6 months ago (when we put our file storage in the cloud), but had found it a bit too pricey. The prices have seem to have come down.
  • A blog on the Confluence blog about how you can turn an application server on and off, so you’re only paying for it when you need it.
There was also an underlying interest. We’ve been working on making it possible to work away from the office for longer periods of time. There’s a quite a difference between working off-site for a day and working off-site for a month.

Q3. Have you seen the Microsoft TV ads with the line “To the Cloud” (link)? What’s your reaction to that type of consumer messaging about the cloud?

Those adverts haven’t been running in the UK, as far as I am aware. The message seems to be the cloud is for when you’re up against a deadline and when you want to be cool. I suspect its aim is to get  non-technical people to associate the word “cloud” with Microsoft, so they go to the Microsoft site if and when they want to investigate what “the cloud” is.

It doesn’t tell you what the cloud is. Collaboration can be done on a LAN, a VPN and a wiki, so it doesn’t tell you how it differs from those options. I guess the key message to the consumer market is: work on any computer, anywhere you like. I’d like them to make some comparison to Google mail (or Hotmail), as many people will have experience of that.

Q4. For tech comm, do you think relevance to cloud computing lies in collaboration (access to more people and networks) or scale (access to more computing power) or another aspect?

I’d say collaboration, bypassing the IT dept (!) and the ability to work from home.

Q5. What’s a great way to introduce cloud computing to technical writers? How do you make it relevant?

I’d suggest real-time collaboration, the ability to work from anywhere, the ability to have a fast system, the ability to test software among a group, user generated content and the ability to make stuff web accessible in a way that doesn’t put any company-critical stuff at risk.

Q6. Do you agree with the statement “cloud computing is becoming “the 21st century equivalent of the printing press” from Nicholas Carr’s blog entry, The cloud press?

No, I believe collaborative authoring/cognitive surplus/wikis are the 21st century equivalent of the printing press – a low cost way to get more people to write (and read) more quickly.

The article does raise the Wikileaks/Amazon issue. Putting the rights and wrongs of Wikileaks aside, Amazon’s actions do show that cloud providers can terminate their service to you in an instant, if they choose to. Although it’s unlikely that many of us will host any thing as contentious as Wikileaks, it will lead people to ask, what would happen if they did pull the plug on us? There are also national laws to consider around data protection – EU laws, the Patriot act etc . We have our cloud data hosted in the European Union, for example.

Q7. How does cloud computing affect tech comm delivery?

It makes user generated content and a more distributed authoring team more possible. It makes it easier to get contractors to use your software.

It means we can do more Webby things with documentation.

The biggest challenge we faced was setting up the server. You can end up in this no-mans land between the hosting service and the application vendor where there’s no-one document telling you how to install the software in the cloud. It’s easier with Windows Server than with Linux, but then you’ll be paying more for your hosting.

Thanks Ellis for sharing your perspective and experiences!

techpubs tools work

OpenStack Doc Sprinting

What a week! I’m recovered and finally able to reflect on our recent OpenStack Design Summit.

As you may have seen on the OpenStack Blog, we gave out three documentation awards to those who made a difference in the latest OpenStack release, Austin, by contributing documentation either on Etherpad or by submitting images or writing RST files for Sphinx output. Contributions have been super and steady and I’m extremely grateful for everyone making doc a priority.

We planned for a day and a half for a doc sprint as part of the Design Summit. In reality, I found myself being approached throughout the Summit by people who are interested in contributing documentation, writing doc in RST, or even pulling printouts from briefcases. The entire week exceeded my expectations.

On the third day of the four-day Design Summit, several of us gathered at a table in front of a projector to work on the documentation. During the week, some of the Anso Labs guys found me in the lounge and we talked about their all-new nova.openstack.org site which rolled out last week. Excellent! I matched up the theme so the swift.openstack.org site now matches. We discussed RST-based doc as the “voice of authority” documentation for developers. Basically, we were all advocating for “wiki or Etherpad as drafting area” and “rst in the source code as authoritative voice about the project” but are open to input on that.

Citrix contributors Zhixue Wu, Armando Migliaccio, and Youcef Laribi contributed an OpenStack Network Overview that we incorporated into the nova.openstack.org site along with a lot of implementation details from Anso Labs. The Citrix group also authored Rabbit documentation and Swift installation documentation which we’re folding into the sites now (and the sprint goes on…). Disney manager Joe Heck documented the entire Nova database schema with diagrams now available on the wiki. Remotely, David Pravec created diagrams showing Nova installation architectures and method and messaging calls which we’re able to incorporate into the site. All of us tested the installation documentation, and Bryan Walker from Accenture added edits for the single-node install based on his experiences. Once they were tested, Anthony Young took the wiki documentation and marked it up as RST to incorporate into the nova developer doc site. I also worked with Jorge Williams from Rackspace about the Rackspace API docs which he maintains in docbook, and Jorge gave me the source files for the Cloud Files API developer guide which we can re-use and incorporate into the OpenStack documentation. We also had a huge collaboration session with Dustin Kirkland and others to create specs for Stack on a Stick, a Live ISO image so you can get Nova running instances painlessly. I also met with Nati Ueno from NTT, who made a working VirtualBox image that runs Nova and we uploaded it to Rackspace’s CDN. Basically these give you Nova in a virtual system so you can painlessly run command to try it out, risk-free.

I hope I haven’t missed anyone – my apologies if I did! I’m finally recovered from the effort and able to look in the rear view mirror and wow, what a sense of pride I have in the OpenStack community.

This sprint felt like a great collaborative effort and gave me a chance to get to know the stackers who want to build great docs for OpenStack. While we didn’t do much future planning, I think we certainly got to know one another and now can comfortably email and comment on each other’s docs – that’s a huge step for anyone writing docs for any project. So I really appreciate all the hard work and want to say thanks for “gellin” through the sprint.

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.

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?

techpubs tools wiki

Wikis for technical documentation – Cliff’s Notes

If there ever could be a Cliff’s Notes for the wiki chapter of my book, I think I’m writing it now. I’ve been working on a great project with MindTouch. I visited them for a focus group with other technical communicators and technical support pros back in February in San Diego. We had open source community documentation represented, we had the health information industry represented, cloud computing, and high tech software writers, Agile writers, and document collaborators. It was a great time, discussing tips, tricks, and the trials of managing lots of content with specific purposes in mind such as learning, education, customer support, technical support, and internal collaboration. The write-up for how to run a focus group of this type is quite good – see Seek Omega: How to hold a Professional Focus Group that Produces Quantifiable Results.

After such a great session, we all continue to talk online thanks to one of the members setting up a LinkedIn Group, and MindTouch also invited us to work on a project to write up specifications for using wikis for technical documentation. We’re basically creating best practices using wikis for documentation, such as:

  • templates, such as DITA’s concept/task/reference as well as FAQ and solution guidance through multiple tasks
  • tags for workflow, assigning tasks, editing, and categorizing pages
  • content collection and curation
  • reports that assist with content curation and community documentation

I’ve been circling back with the members of the focus group while I write these specs, and working with Steve Bjorg, the CTO for MindTouch. His attitude towards development is,  create something with a sense of openess and collaborate with users as early as you can. It’s a refreshing way to make software. He describes these first go-rounds as the “Cliff’s Notes” for creating technical documentation with wikis. It’s not as robust as other solutions yet, but it sure does have features that are exciting glimpses at the future of documentation. I’ll post more in the coming weeks and months as we round out the features.