Monthly Archives: April 2010

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!

Interview Techniques for Users

I had a great talk the other night with a classmate of mine from graduate school, who focused on usability and now works on a web application development team as their user experience designer. He’s Tim Keirnan, and I asked him to explain some of his interview techniques that he uses for his Design Critique podcast. I also got great snippets about his user interviews.

I just marveled at how dedicated he is at getting user information, no matter what the situation. Just acquired a company in an eastern European country? No worries, set up a remote meeting where you can view the user’s desktop. Think your users don’t know what they need in their daily workflow? Ask the right questions with the right context and you’re halfway there at least.

  • Don’t ask people to project into the future. For example, asking “What will you do with the Intranet tomorrow?” sound ridiculous if you phrase it that way. Instead, ask about today, this week, this month.
  • Don’t ask them anything without having artifacts in front of them to spur discussion, even if you have to use Webex because you can’t travel to their office.
  • Do ask users about their daily work.
  • Do ask about their last mistake and what they think they could have done to prevent it.

These are just a few notes I jotted down after talking to him. Since most “interview techniques” posts are about job interviews, I wanted to find more user interview techniques. There are eight articles about conducting usability interviews collected on the EServer TC Library. One essay titled Nondirected Interviews: How to Get More Out of Your Research Questions on Adaptive Path says to concentrate on immediate experiences, which really hit home with me. At SXSW Interactive, much ado was made about context. And context in interviews – both time and place – can make or break the value of the user research.

I ponder this idea of context as I search for user data on the social web. Perhaps the loudest users are on social media but not a good representative of true users, depending on the product. I’m thinking of the information you can get about job titles, job descriptions, tools used, and so on from a site like LinkedIn or Indeed.com. I described finding your user’s vocabulary previously in a blog post last year. What do you think? Should you emphasize and use the online personas you can build from social media sites, or call that publicly-available information suspect and marginal?