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.

• All of the manuals on FLOSS Manuals site are authored and displayed in a customized Twiki wiki.
• Sun Microsystems (now Oracle) has many documentation wikis. The OpenDS Wiki offers a nice example. Also all the OpenOffice documentation is available on a wiki.
• Mozilla Developer Network
• Adobe Labs wiki
• Splunk product documentation
• Atlassian product documentation, specifically the Confluence documentation
• OpenCloud
• GigaSpaces
• Firefox Support Knowledgebase
• Second Life In fact, they single-source their embedded online help with the wiki as source.
• Ubuntu
• RightScale
• ExactTarget
• IBM developerWorks Wiki
• The MSDN Library from Microsoft offers many wiki-like features.
• Embarcadero RAD Studio wiki is actually 9 wikis, read the manager’s blog entry about it.
• WebWorks Documentation Wiki
• Tideway (now BMC Atrium Discovery) documentation

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.

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?

I haven’t done a round up of other places I’ve been writing lately, so I thought I’d offer a roundup of articles I’ve written for other sites.

What I’m writing

10 ways to motivate employees to use your CMS – Fierce Content Management

As a content strategist, what motivations help you meet your content goals when integrating a content system? Often the tool selection gets the most attention, yet the motivation of contributors is going to make or break the success of the project. Motivation is a psychological feature–a willingness to act that precedes behavior. You might think of a points system with rewards as a motivation system, but rewards are only one type of motivation. Read more

Putting the User in User Assistance – WritersUA

People on today’s social web are accustomed to participating in conversations, having a voice, giving opinions, offering reviews, and generally interacting with content and with each other like never before on the web. How can we enable users to respond to or contribute to user assistance? The answer could be a wiki, but a wiki is not required to enable more interaction with users. Here are some specific techniques, starting with the simple and moving towards the more complex, including wiki implementation practices. Read more

What I’m reading

I’m also posting reading items to my delicious.com/annegentle account that might interest my blog readers.

First Steps in Flex Screencasts

We meant to do that… (part I) | MsCyra’s Web Development Blog

How developers learn survey results – interesting

WDVL: ‘Users’ Versus People–Understanding What Motivates Online Behavior – Page 2

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.”

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?

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!

I’m reading (with vigor!) the The State of Community Management Report: Best Practices from Community Practitioners
from the Community Roundtable, and finding so many wonderful tips about content from people who are community managers. I had to start a list of items that are relevant to technical communication and web writing to share. I naturally tend to target technical communications when I interpret the report, but this report is rife with content strategy.

I agree with this statement, and I think it means a positive impact on technical writers and web writers who are paid to create content by businesses.

The percentage of content that is desirable and
feasible to be formally produced versus community-generated
will have a big impact on resource and
budget planning. This aspect is likely to change – often
dramatically – over time, although it should not be
assumed that content should ever be exclusively
community-generated.

I personally haven’t found that completely community-generated documentation will serve most business goals. In the case of FLOSS Manuals, though, the community-generated content meets the main purpose of supporting and documenting  open source software. Still, hiring professional writers makes sense when you need to create content that meets very specific goals for a community, whether your goals are raising awareness, troubleshooting, or learning.

Now, this particular comment puts a bit of a stake in the heart of technical communication’s beloved single sourcing. I like the idea of associated content for technical writers to create. It’s branching into new media, such as audio or video, while still valuing the technical content that you work so hard to create. It’s not that one births the other, but rather the two types can compliment each other.

Instead of directly repurposing content from one format to another, create
associated content. For example, instead of turning a white paper into an
audio transcript, create a podcast discussion about it with the author.

Another line that causes me to press pause and ponder for a bit:

People seldom form relationships with text alone.

Instead, offer images, video, or music as part of the user experience in order to grow relationships. Fascinating.

And finally, the one that might be the toughest for professional writers, copy editors, and technical communicators to accept:

Learn to accept imperfection. Concentrate on making content interesting
and relevant rather than perfect. Imperfection actually allows community
members to better relate to it and engage with it.

And with striving towards imperfection as my excuse, I’ll close out this blog entry and encourage you to read the report for yourself, drawing your own arrows from the quiver and targeting what is important to you.

For this month’s Central Texas DITA User Group meeting we played host to Eliot Kimber. I took some scattered notes, mostly jotting down the great phrases Eliot handed out while nodding and chuckling.

He’ll be doing this presentation as a webinar for Really Strategies, Inc. on March 10th, 2010 and you can sign up on the Really Strategies website.

Eliot is explaining why DITA makes sense for publishing outside of tech comm – because most all publishers need to get ePub out of their legacy content. NEED.

DITA should take over everything – Eliot has an evil plan. He tries not to put his pinky to his chin, though. He uses strong statements, though, like:

“No reason to choose any other XML standard but DITA.”

DITA for Publishers is built on/with/using:

• Topic types: article, chapter, subsection, sidebar, part
• Map domain: pubmap
• MS Word to DITA framework – XSLT-based framework
• ePub transform for Open Toolkit
• Pubmamp support for PDF transform, which enables creating quick drafts for review while people offshore the XML-izing of the content

Example of just how exacting and demanding editors at publishers can be: Quark to Indesign migration blocker (years ago) was that a particular hyphen character wasn’t automatic with Indesign.

Eliot on publishers deciding to go with XML: “If they’re really lucky, they have an IT group that won’t help them with decisions on XML solutions.”

What Publishers need that DITA brings: (bold emphasis mine)

• Low cost of entry for sophisticated XML solutions
• Blind interchange of content
• Flexible markup design
• Strong support for modularity and reuse
• Wide support by free and commercial tools

He got tired of reinventing the same thing over and over – DITA for Publishers makes his implementation job easier – more clients farther along a path of success.

Doesn’t DITA require modular writing?
- No

Most people implementing DITA have one topic, one file – but that is not necessary – he could have an entire book as a single XML document with one root “topic.”

Who’s using DITA for Publishers?
- ASTD is using it for their publishing of books and magazines
- Upper Room – Methodist church – publishing arm of major No. American church for books and magazines
- Publisher of test preparation manuals – including TAKS test – using learning and training specializations for test questions as well
- Any Really Strategies client who doesn’t already have schemas (or who is willing to migrate to a DITA-based solution)
He usually can get at least one output that they can’t currently get out of their current XML schemas

Publications are very simple – except when they’re not. One differentiator that publishers can use is the design of the book – unique, attention-getting designs are valued.

DITA enables iterative design and development – when you come across something more sophisticated than the “norm” you just keep adding features – and interchange is always ensured.

Map / Content distinction is essential – chapter, sections, subsections, but publication structures can be very complicated with appendices, glossaries, indexes. Maps can impose the semantic meaning within the context of a map structure. So you may have one kind of division element, but 18 kinds of topic reference (yow, but that makes sense.) Means he can convert easier to generic topics, but add sophistication through the map.

Lots of publishing content is highly modular -

examples:
magazine articles – reusable, valuable, can send through email, post to web
encyclopedias
travel and nature guides – can be recombined in interesting ways to provide additional value – also batch consistency over a large number of pubs makes sense (automated composition is a-okay)
Dictionaries
Newspapers
Sidebars – by its nature it’s a standalone thing
Educational materials such as textbooks
Standards – people make money publishing info about accounting standards, for example

Business rules apply to element types in their CMS – so there’s a practical aspect to article, chapter, subsection, sidebar and their nesting

Bookmap is way too limited for technical manuals that don’t conform to IBM standards

Bookmap doesn’t give publishers what they need, so he built a publication map domain – provides more structuring options, more licensing options (nothing to do with copyright), he can also mix it in with other map domains, e.g. learningMap

structural module vs domain module – you can pick and choose in a domain module the things that are specifically useful

Provides publishing-specific structures, such as “page” – can have a topic with an empty title element

Publishing domains:
+ Formatting domain
- supports capturing of arbitrary formatting (example: 9th grade biology text book – lots of nutty formatting)
- Integrates MathML
-Can embed raw InDesign interchange data
+ Pub content domain – elements contained in typical publications, e.g. epigram
+ Verse domain: markup for poetry
+ Classification domain: container for classifying metadata (specific taxonomy, Upper Room has this for all the ways their content relates to the domain of spiritual “stuff” he used a DITA map for the taxonomy)

General purpose Docx to DITA XSLT transform – authors are writing magazine articles in Word and then submitting. Transform configured by separate style-to-tag mapping. Everything from magazine articles to entire course scripts, all with different configuration parameters. Must have consistently tagged styles in the Word document.

XML-first workflows are pretty rare in the publishing industry among publishers.

Too much variablity in the business process – eight different biz processes through which they get books to publish at an association, for example.

Typify can “remember” where things came from and automate composition, but it costs a bunch.

DITA to InCopy generates InCopy articles from DITA topics – InCopy is used for manuscript preparation (writing with no layout).

The ePub open toolkit plugin generates HTML-based ePub packages from maps
Uses output of the base XHTML transformation type

What he wants to continue after DITA 1.2 is done:
- Documentation of vocabulary modules
- Refinement and extension of tools an infrastructure

Community of DITA for Publishers users is building – he wants to propose it as a DITA Subcommittee once he gets enough community behind it.

I finally did it, I wrote my first article for the Demand Studios content farm site, eHow. I wasn’t playing the part of a content farmer, though, but rather a farm worker, writing an article for little pay (compared to other rates I have earned as a professional writer).

I signed up for Demand Studios a few months back. There is a company called Pluck here in Austin that was acquired by Demand Media in the spring of 2008. What drew me to them in particular was not only the local connection, but also a fascination with turning search engine optimization on its ear. I first learned of these methods for content creation from this Wired article, The Answer Factory: Demand Media and the Fast, Disposable, and Profitable as Hell Media Model. Basically Demand Studios analyzes what phrases are searched for and then enter an article request in their database. There are currently 15,000 articles waiting to be written in their system. The pay for those articles is from $15 to $7.50 or less, and there are some assignments that offer profit sharing based on the numbers of views, apparently.

As a pro writer, I was dead set on following the style guide, knowing that attentiveness to the guidance given is part of the battle in producing good content. In their system, when I “Claimed” the article, it wasn’t immediately apparent which template I would be writing to, which made me a little nervous about attempting it in the first place. After clicking the article to claim it, though, I found that it was the About template. The guidelines were very clear – the About type required five sections with one-word section headers and the first section had to be titled Overview and contain about 75 words. The rest of the sections could contain more than 75 words but at least 50 words were necessary, and overall the article was targeted for 400-500 words. Quite structured.

The web-based authoring forms were easy to use, though it did not include a word count. I found it easier to get word counts in Textpad and then copy/paste the text into each section.

They’ve also very recently introduced an image library that you can search for images, the use of which is encouraged. You could add an image to each of the sections if you wanted. To my poorly trained eye, they seemed adequate but not too glossy, and none of my searches found quite the perfect image, but I included two anyway. They intend to allow people to upload their own photos, which I would have done in a heartbeat as I had one or two that would have been just right.

To my relief, the article I submitted by noon on a week day was approved by early morning the next week day.

It took me about 2.5 hours to write a 500 word article, I’m not proud to admit (or perhaps I should be proud of the quality that comes at that speed?) So my hourly rate for the article was right around $6.00 per hour. At least I didn’t have rewrites (she says sheepishly.)

To reflect back, I did the article because I wanted to see what the authoring system was like, and experience for myself the process of writing in such a system. To be sure, it’s easy to demonize such a system when you’re accustomed to higher pay for content creation. There’s a great interview on ReadWriteWeb by Jay Rosen, who talked with Demand Media founder and CEO Richard Rosenblatt, and it offers both sides of the issues surrounding content collection and the future of the web. I don’t want to take sides by sharing my experience. I just wanted to collect information based on the writer’s experience.

What do you think? Are content farms cluttering the web and driving down writer’s pay? Or is there an entrepreneurial opportunity here that offers a low barrier to entry for content creators any where to earn pay for  populating the web with content that’s already being searched for?

While doing some research for LugIron, a startup here in Austin where I serve in an advisory role, I found a slideshow discussing signs of successful community launches by Joe Cothrel, a VP of service at Lithium.

Now, what they mean by “community” is a larger than 5,000 person audience, enterprise-type (B2B or B2C focused communities), and containing primarily forums and blogs (followed by everything else.) So, it’s not quite the same as the wiki communities that I’ve studied and participated in. But, what’s interesting to me is that one of his Warning signs on page 8 is a quote from the enterprise:

“We want to do a pilot.”

Huh? Really? Wanting to do a pilot is a warning sign of eminent failure? I guess with blogs and forums, you would want full dedication to the efforts and the goals of the community. But with wiki communities, I think a pilot is a great idea. Pilot content, pilot collaborators, pilot wiki.

What do you think? Do wikis fold up easier than forums? Are pilots getting a bad name in corporate-sponsored communities? Is this a case of the vendor wanting full dedication in their sales engagements?