Tag Archives: wiki

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

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.

Booki in the running for a Drumbeat Award

Adam Hyde, founder of FLOSS Manuals, the community documentation group that makes open docs for open source, just announced some exciting news on the FLOSS Manuals Discuss list.

…we got booki into the Drumbeat
Open Web Award…ok. Thats great news! Well, now we need to get votes
since there are 3 projects we stand a very good chance to win the 5000
cash (which we will use for a code sprint)

so…if you want to vote go here:
Open Web Publishing

Register and vote!

This is exciting news! Registration and voting was a bit wonky when we first sent people to the site but I think it’s all worked out now and we have a great shot at this. Please help out if you are so inclined.

The timing of this announcement seems well-aligned – just yesterday I wore the “Adopt Mozilla” t-shirt that I received for donating to the Open Web fund.

So, whether you support a baby Mozilla or a baby Booki, let’s keep the web open and support open documentation and publishing while we’re at it. Read more about Booki at the Booki blog.

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.

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.

wiki writing

Wikis, copyright, and licensing

A question about wikis and copyright came through my email inbox this week, and I thought I’d share it with my readers. It’s a good question and a common misconception of wikis is that all content is always liberated once it’s put on a wiki. Not so, and here is additional explanation.

Q: A colleague of mine is putting together a corporate wiki for engineers, researchers, and IT people and is concerned about wiki articles infringing on copyright for outside sources. For example, definitions of common terms, discussion of underlying concepts, etc. Is it sufficient if these items are reworded and paraphrased? If not, are citations required?

A: An excellent question. I think that people get a bit confused about the difference between protecting copyright and using licensed content correctly. I’m also surprised at how often people connect wikis to “content stealing.” 🙂

To pull from a blog post I wrote on the topic as a follow up question to my book, Choosing a License for Sharing Documentation Content,

“Copyright was intended to protect the creator from publishers publishing the content, “to the Ruin of them and their Families.” That ruination quote is pulled from the Statute of Anne, considered the origin of all copyright. Licensing the content is one of the things the copyright holder can do with the content to indicate how they, the creator, give permission for it to be used, sold, distributed, and so forth.”

To create a checklist for someone who needs to create, say, a glossary for IT-related definitions, you could use something like this list of questions:

  1. Is the content you’re using as a starting point licensed? If so, what does the license allow in terms of reuse, redistribution, and so on?
  2. If the license allows for attribution, have you attributed the content correctly? If there are other requirements for the license, can you meet those requirements?
  3. If you still want to re-use the content but it appears to be licensed in a way that prevents that, you can either contact the copyright holder and ask permission to use the content or rewrite most of the content in such a way that it becomes your own. A “rewrite” for reuse stance is the least defensible and may have the weakest rationale for the content’s reuse, however.

A walk through on current content reuse on a wiki may be helpful. If you wanted to walk someone through an example, you could use Wikipedia’s image pages – each image has a rationale for its placement on Wikipedia. From their Help:About page – “Every image has a description page which indicates the license under which it is released or, if it is non-free, the rationale under which it is used.”

In the previous post, I talked about licensing your content so it can be used. In this post, I talk about using licensed content. I’m sure there are other, more complex angles for content and reuse. Feel free to discuss!