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.

After a Q&A on the Facebook discussion page for my book, Sarah Maddox and I had an additional email exchange talking about the difficulties people face when using wikis for documentation.

I believe that many wikis are in the range of “content management systems” or moving in that direction. But there are many difficulties in general with content management. Here are some areas I’ve heard from fellow technical writers:

Access control: Without being able to say who can view or edit what, some wikis are impossible to apply to tech doc due to serving specific business reasons with the content. A customer support article should not be subjected to multiple edits from wiki spammers.

Hierarchy: Without at least 2 levels of hierarchy, tech writers are stymied as to how to use a wiki without hierarchy. Of course. We have complex documentation sets to maintain and hierarchy is a natural way to organize topics.

Version control: The difficulty in maintaining or tracking several versions of a bunch of topics (or an entire namespace/space) to correlate with a software release version is frustrating to many – I’ve heard this is a basic problem for WordPress’s Codex.

Global search and replace – and don’t forget spell check: Writers are used to maintaining giant Framemaker docs where they could spell check and search and replace across large amounts of content. CMSes and wikis don’t make that so easy as before.

Search on the site itself: We’ve all become so spoiled by Google’s search algorithms that any local search engine usually comes up short.

Workflow: Wikis can be weak in workflow, even as simple as “approve or reject” a particular article.

Creating collections: More than just outputting to PDF, people want to single source from a wiki to create collections of articles based on tags, categories, labels, and so on.

Offline access: Many wikis think they’re the end destination for readers, but the classic scenario is “what do my readers do if they need to get on a plane?” One clever solution to this problem would be to offer the wiki on a USB stick – call it a wikiscicle.

Round tripping: Writers are always talking about roundtripping content. I’ve usually dismissed it as not worth the trouble – there wouldn’t be enough contributions that a team of writers couldn’t keep up with. I’ve finally heard a decent business case for doing so – from structured XML (DITA) contained in a CMS to wiki and back again. Translation (to 22 languages) and volume of edits or contributions are the key to this scenario.

One-click publishing (batch processing): On release day, you want to set all topics to released at once, but with many wikis, you have to go to each page one-at-a-time to click them over to the right state for release.

With plugins and advanced wiki engines, these hurdles are easily overcome. But Mediawiki, a popular wiki engine, flunks the first two tests that many technical writers would apply. These are the examples I’ve seen and some of what Sarah has experienced. How does it match up with your viewpoint?

This week I’m finishing up an Agile sprint. Not just any sprint, though, my last sprint as a technical writer embedded on a sprint team at ASI. I’ve learned so much there in the last couple of years that I’ve decided to make a go at consulting. I want to help people with content strategy, social media, and any tools they need along the way such as collaborative authoring, wikis, web content management systems, or DITA.

This week is my last Agile sprint for a while, but I think I’ll adopt some Agile principles and apply them to my new work lifestyle as an advisor for LugIron and a contractor for Informatica here in Austin.

1. Only deliver things that an actual customer would find useful.
2. Deliver something that I consider to be done, shippable, and customer- ready.
3. You can do any task, no matter how daunting, if you slice it thin enough.
4. You should list and prioritize all tasks, large and small, that get you incrementally closer to your goals.
5. Create prototypes all the time, no matter how rough or simplistic. Keep polishing as you go.
6. Reflect periodically, and change what’s not working well.
7. Understand the business goals. Clarify when needed by asking questions and seeking the details.
8. Welcome changing expectations and requirements. Embrace change.
9. Maintain a sustainable pace. I should be able to maintain a constant pace forever.
10. And if all else fails, don’t overthink it, and go get a beer.

As a guest post on The Agile Executive blog, I was invited by Israel Gat to describe book sprints as an Agile method for documentation. Here is the beginning of the post and I encourage you to read the rest and comment on it there.

One of the Agile Manifesto’s basic balance equations is valuing working software over comprehensive documentation. This line of the Agile manifesto can be confusing to some supporting roles in an Agile development enterprise. As technical support staff, trainers, and content creators, what are we doing to fit into this Agile methodology, and what’s working well? Let’s explore some old habits that need to die, and some new rituals to fill that space.

Nowadays, Google’s search power offers software users access to documentation through forums, mailing lists, even through blogs and wikis maintained by the developers and authors themselves. These new conversational methods for documentation, support, and education have opened new opportunities for those groups to add value to software adoption. Ways to provide additional value to the working software include helping people learn the software, troubleshoot the software, or do their job with the software. Education, uptake, and support are all integral to the overall value of a software product.

Value proposition

First, a discussion on the value added by good websites, updated and relevant training materials, and a helpful support staff.  Those departments want to avoid the continual cost center perception. To do so, they find ways to add to the bottom line, such as:

• increasing sales (enterprise) or increasing adoption (open source)
• keeping users happy and satisfied
• adding contributors to the community, whether helpful troubleshooters or prolific coders
• decreasing support costs (in time and money)
• converting participation into value
• increasing positive perceptions of the software

In my experience, these values are universal to both enterprise software and open source software. Let me share my story.

I spoke with Rachel Potts, technical communications manager at Red Gate Software this week. They have done an innovative, seamless content combination for their Support Center (red-gate.com/supportcenter) to combine Author-it HTML output with technical support articles. Forums are one click away from those articles, and the authors include both technical writers and customer support pros. As she describes it herself, “The Red Gate support site is a help and support portal that comprises content such as product help, a knowledge base, marketing videos and public forums.”

I’m impressed and enjoyed speaking with Rachel about how they combined content from different sources. To integrate their output with the customer support articles, massive XML transforms are built against the Author-it output to populate the custom content management system that runs the support website. The content is not locked behind a support login, though.

Rachel has written an extensive article about their use of Google Analytics on the site, titled, What can web analytics do for technical communications? It’s a great article, one I’d been hoping for, that describes the useful metrics and what to glean from those data points, such as page views, unique page views, exit rate, and time on page. She also extensively analyzes search data. I also appreciated the section on identifying pages that no one reads. Fortunately, they don’t have that problem with their content.

She’s looking for examples of people who are pulling content from multiple authors in different areas in the company and also people outside of the company. Here are the three I sent her.

• Adobe’s community help search is described on this page, and you can link to it to try it from there as well: http://community.adobe.com/help/about.html. It’s described as “This search index includes content such as product Help, language references, TechNotes, Developer Connection articles, and Design Center tutorials as well as the best online content from the Adobe community. Searchable content is chosen by experts at Adobe and in the design and developer communities, meaning you find the focused answers you need faster than with any standard web search.”
• Sun Microsystems has projects where technical writers are gathering different types of content. NetBeans Ruby is the project I heard about at the STC Summit in 2008. Here’s their wiki: http://wiki.netbeans.org/Ruby. They post screencasts and tutorials to http://mediacast.sun.com.
• Cisco has done some remodeling on their support community, for the better, by combining more content: https://supportforums.cisco.com/index.jspa.

I’m interested in hearing your examples as well as talking to people who have cast a wider net to gather content for support sites. What are your favorite sites, either as a consumer or creator of support information?

I loved the line, as delivered by Tom Hanks in A League of Their Own, “There’s no crying in baseball!” I know there are times when the crying must happen without delay. I don’t believe most workplaces actively encourage crying – at least not outside of acting careers.

When I’ve read Agile practitioner reports that tell tales of times when technical writers have left meetings and fled to cry, I am not just surprised but a little dismayed.In A Tale of Two Writing Teams from an Agile conference three years ago, one anonymous writing team reported one writer in particular crying during the daily standup and in retrospectives.

As the prioritization changed from the new Java web program (the new and fun stuff) to updating the old, stuffy legacy client server code, writers’ tasks switched from creating new online Help to updating old versions of end-user documentation (books). This change caused the writing team to revert to form—that is, they began to demand written design specs. It’s as if once the technology took a step back from online Help to written documentation because of the prioritization of the product backlog, so did the methodology choice. I tried my best to coach the writers to work creatively with developers on the old stuff as they had on the new, but there was an insistence that the existing specs
for the old legacy code would now become outdated, and the writers were completely uncomfortable with that. One writer—the one with the most tenure—
moved out of the team room, citing lack of privacy and her ability to contribute as the reasons (when I know that it was really a lack of embracing the change). I can remember several episodes of her crying during daily scrum meetings and in
retrospectives.

The paper author’s analysis indicates that the stress of embracing change caused the outburst I think the stress of change can bring on an emotional outburst, and sometimes people have crying as their stress release.

But what is more interesting to me as a content provider is that the change in the tools used to deliver the documentation seemed to correlate to the writer’s work habits. As I search for wiki solutions for collaborative authoring on Agile teams, I’m reminded of this article again and again. There’s no crying in Agile, and having an Agile documentation tool should help with change management. Except, of course, the change management associated with bringing in a wiki. Stewart Mader had great suggestions at the recent WebWorks Roundup: make wiki upkeep part of everyone’s job, make it as easy as email, and make it as sociable and enjoyable as riding the train to work each day. Any other ideas? I’d love to hear them.

At FLOSS Manuals, we have been using a method called a Book Sprint -  collaborative authoring, one week at a time. In fact, Google’s “Summer  of Code” project has sponsored two of these sprints. The latest was  just this month for a completely open source video format called Ogg Theora. The sprint got a mention on slashdot last month.

The idea of a Book Sprint is that you can get lots of documentation written in a focused amount of time with the right team and some amount of content already in place. Gathering people in the same room when possible is extremely helpful and motivating as well. I like to think of it as using two wiki patterns – the Scaffold pattern first followed closely by the Barnraising pattern.

I often get questions about the viability and value of a book sprint in a corporate environment. Here are a couple of ideas for running a book sprint at a company.

Agile software development

In an Agile environment, the term “sprint” means a timeboxed iteration – a time period could be two weeks, or it could be three or four. You plan out the “sprint” based on the number of people you have and by correctly sizing the documentation goals for the sprint.

The term Book Sprint seems appropriate in an Agile environment. For example, plan the sprint to have the team focus entirely on doc for that iteration. That’s one company-type application.

Scenario-based documentation by Subject Matter Experts

Another company method of focused authoring that I know of is the one that IBM employs to write Red Books. A document coordinator brings in  the subject matter experts, they outline the RedBook in a day, then assign chapters to each Subject Matter Expert (SME). The SMEs usually go off and write for a while, then the RedBook comes back together with the document coordinator (I think this is accurate, but please do feel free to offer more detail by commenting).

Chris Almond gave a presentation at Central Texas DITA User Group meeting last year about using wikis for RedBook authoring – his slideshow is available on slideshare.net.

Writer’s luxury accomodations – seclusion and focus with collaboration

For Book Sprints, what we do is try to get a good group of people a great place to stay for a week and write. There’s at least 4-6 weeks  of pre-planning of the outline and possible content that already exists so that the sprint itself goes smoothly. Getting people to agree to audience and scope ahead of time is crucial. A book sprint  basically forces documentation decisions and priorities under pressure of one week’s time – so you want to get lots of questions out of the way before the actual sprint.

We also make them fun and offer food and “after hours” activities. The fun is crucial!

I just joined the Writer’s League of  Texas, and they actually charge people for writing retreats that sound  an awful lot like a book sprint, except that they’re not collaborative, they’re for solo writers to get writing done in a nice, supportive environment. It’s basically a nice location with some fun planned in as well.

We have case studies and lots of planning in a Book Sprint book hosted on FLOSS Manuals at http://en.flossmanuals.net/booksprints. Also,  the free sample chapter from my book talks about Book Sprints at length, see http://justwriteclick.com/book, and shows how much funding we needed for a book sprint last August that produced about 300 pages of printed PDFs and online HTML-based help.

Today I gave a presentation remotely to some members of the Society for Technical Communication (STC) called “Climbing the Levels of Collaboration: Or, How to Harness the Power of Crowds (or your Coworkers).” I enjoyed the questions the most. Surprisingly all the questions were asked using the chat area of the conferencing software, not audibly on the phone.

I think people learned a lot. It was interesting that we veered off much more into Agile development territory than I had intended. One writer was in an organization just starting Agile development, and wondered how to work with documentation that was in chapter-based books. My suggestion was to do a content audit of those chapter-based books to try to determine what topics make up those chapters. Then, try to match topics with the Agile stories that your team would work on in a sprint. I must have content audits on the brain while reading by Content Strategy for the Web by Kristina Halvorson.

Here is the slideshow on Slideshare. You can also download a four-page PDF of the slides.

Lisa Dyer and I have co-authored another paper about structured wikis, using DITA as the structure for the wiki. The paper contains specific ideas about using wikis both internally and externally for software engineering processes and software documentation.

Our assertion is this: While either waterfall development methods or Agile development methods could benefit from the collaboration a wiki offers, we believe that DITA typing combined with the wiki collaboration offers even greater benefits than DITA alone or a wiki as a standalone authoring environment.

We think this one is worthy of a price tag, so it’s available for sale here at Just Write Click. You don’t need a PayPal account to purchase if you click-through the links that don’t require you to login to PayPal, you just need a credit card. Once you purchase it, you’ll go to a page with a download link to the PDF file. We’ve discontinued the selling of this paper and thanks to those of you who purchased it, read it, and took off with the ideas!

You can now download the paper originally submitted to the Wikis 4 Software Engineering at WikiSym 2008.

We’ve revised it based on feedback from three reviewers who had excellent commentary and were not technical writers, so it should contain useful information for technical writers, developers, software engineers, business analysts, project managers, and quality assurance engineers.

I had a great time in Philly for the STC Summit, and here are some of my takeaways.

Collaboration is a huge part of our jobs, whether it’s finding others in your company to collaborate with as the two technical writers from Sun have done while creating screencasts with a “rock start developer” or the collaboration they do with users as they became community members and sometimes moderators, collaborating with the developers who use the product they are documenting. Collaboration means that you’re willing to learn another’s language, whether it’s another country’s language or learning the vocabulary of Scrum. Collaboration and structure can work together, such as the power of collaboration on a wiki, if you can find a common language (or currency), such as DITA.

My manager’s takeaway had a lot to do with Agile, and I see Agile as the ultimate collaboration mechanism for writers to integrate themselves not only with the development team, but also the business analysts who take the product to early beta with customers, and in that way, technical writers can get even closer to customers. I wrote an article for the CIDM Newsletter last year with ideas for thriving and surviving an Agile environment, so the topic is near and dear to me, but since I’ve not had to be part of an Agile dev team since leaving BMC, I chose not to focus on those sessions. I enjoyed the writeup by Richard Hamilton describing Mike Wethington’s Agile talk with each slide as a sprint followed by discussion. Agilists are living’ it, folks.

Conversation was another theme I chose to follow, due to my interest in writing a book on the topic of designing conversation and community into documentation. I was fascinated with the Asynchronous Conversation talk that Ginny Redish gave and she offered so many examples of how even the writing you do can be re-written to be more conversational – not just having style guides that allow for informal style and voice, but also removing passive voice, ensuring you know who’s the actor and what is being acted upon, and so forth. Confirmed my instinct that conversation, collaboration, and content are close cousins if we can figure out how to best combine them all.

Community is a huge part of what I have been paying attention to, and the sessions I attended and the attendees I spoke with gave me more insights into tapping the power of communities. I also found it fascinating that speakers at two different talks (Sun and IBM) mentioned finding “celebrities” when building wikis or screencasts, because communities wanted to watch the “rock star” work while they built the wiki or listen (and speak back) to their heroes while the heroes did their jobs as a subject matter expert.

Career plans and the business aspects of convincing others where your worth lives as a technical communicator were constantly brought up in the question part of the sessions. How did you prove that a wiki and screencast were the right way to take the content, when the online help had to be further minimized to do so? In our collaboration panel we were asked, what if you’re in an environment where obviously the wrong tool was chosen for a technical publications group, yet the writer felt powerless to prove the absences of ROI (Return On Investment) for that particular business and tool decision? I listened to these questions with a heightened sense of awareness of my own weakness in this area. While I can implement great ideas, proving that the idea needs to be implemented in the first place means understanding how to convince management of the value.

So, putting your manager hat on, where’s the value in conferences?

I read Tom Johnson’s notes from the conference with interest, and while I haven’t asked him this specifically, I think he and I share some struggles of attending and presenting at these conferences – we’re often invited, sometimes compensated, but it’s not our “job” to attend and present, as it is for the consultants of the world. I’m a reluctant traveler, though eager presenter. How can I justify the time and expense? Believe me, I have to justify to myself and my family before I even purchase a plane ticket, step foot on an airport shuttle, or draft up a Powerpoint slide deck.

My overall plan is that I try to go to the STC annual conference about every other year, when I’m not pregnant, ha ha. Before Philadelphia, the most recent annual STC conference I attended (and presented at) was three years ago (is that right?) in Baltimore, Maryland, and for some reason that one did not seem as “big” as this one. With probably over 1,300 attendees, Philly felt large to me, even though SXSW Interactive was probably the largest attendance I’d seen at a conference recently with over 9,000 people there just for Interactive.

Personally, I’m finding the value in interactions

I hope she doesn’t mind if I mention this, but I owe a huge thank you to Char James-Tanney who listened to my internal struggle via email while I hemmed and hawed over whether to attend the STC Summit at all this year. Working parents know that the burden is placed on the spouse at home with the kids, and my husband rocks all over the planet when they have “boy’s club” days with me. But. Family life lately has involved some funerals, minor medical issues, and just plain life, which always complicates travel plans. And then there’s things like how much really young kids grow and change in a matter of days. For example, my 18-month-old son who couldn’t reach doorknobs before I left for a conference, could open doors when I returned. And that was after a four-day trip!

Yet I have always found that the people I talk to and the relationships I forge in face-to-face meetings show enough value to make the travel hassle and lost kid growing time worthwhile. Heh, I wonder what my sons will say when they read that in ten years? I also believe that it can be good to be away from family just so you appreciate what you have when you return. I know I do.

Sarah O’Keefe and Scott Abel have been wonderful for me to simply email or call when I’m looking for mentors in this strange grey area between (not) consulting and offering expertise on the web. I didn’t necessarily have to attend a conference for these generous people to let me reach out, and it’s plain fun to get to know them.

Balancing act, of course

What I’m trying to do lately is find a balance and see what I can do to share my knowledge remotely and do a lot of blogging, emailing, e-networking, and local networking. Austin’s a completely awesome place to work and live and meet others who are forward-thinking, business-minded technical writers and managers. Heck, I can meet them for lunch, and not have to travel further than a few miles to do so. I’m also finding ways to collaborate on STC services with STCers around the world. I’d love to hear others thoughts on the balancing act and whether it changes as your life at home changes. From what I’ve observed, the long view is the most varied view when it comes to participation in STC and conferences.

What I mean by that statement is this: some of the greatest, most active STCers I’ve been fortunate to know, hit their stride when their kids went to college. I plan to be around STC for the next 20 years at least, and I’m already nearly 15 years in. STC is the kind of organization that can support that long view if my observations of others are any indicator.