Monthly Archives: April 2008


Product web site design

I’m reminded of the power of the product site by this post from the meeblog, the meebo blog. Meebo is a web-based Instant Messenger for multiple IM platforms such as Google Talk and AIM together in one interface. It’s extremely handy, but apparently a product website redesign has really pushed their visibility even higher. I thought, that makes perfect sense. When people understand the uses for a tool, they use the tool even more readily. Here’s their new product site. The meebo repeater apparently got even more attention lately due to this redesign. I don’t think it’s that they made it easier to use, it’s that they explained a scenario for its use – When meebo access is restricted, install this small piece of software on your home computer to access meebo anywhere. Simple and elegant.

I’m now looking for short explanations for why you do things with the product I document, iMIS. A task overview is part of our templates now, an overview that states the principle of why you want to perform the task. In my mind, though, there’s a subtle difference between a task overview and a scenario for why you’d want to do a task. This forced question, why? is helping me write the correct tasks for the user’s goals. It’s not necessarily part of the product site, but it is helping me understand what

Another reason why I’m reminded of the power of the product site is because of the summary in Scriptorium’s white paper, Web 2.0, Friend or Foe? Four out of six of the bulleted list of integrations that summarize the paper refer to the product web site. We need to remember that unless we integrate our help systems, we risk not answering the right “why?” questions for our users.


Putting content into context in a wiki – especially in a large environment

An interesting read on the front page of of all places. I enjoy random clicking, and this one came up with a great commentary on the difficulty of using a wiki to get how to information.

From Learning about Second Life from Google:

Over at SL, the main source of information is on the WIKI, which in my opinion has some great information but because Linden primarily lets the users run the show isn’t as helpful as some sort of information clearing house. Trying to sort out how to sculpt, for example, is an exercise in total frustration. There are some wonderful tutorials, but SL does nothing to properly aggregate and put these tutorials into context.

I wonder what Second Life could do to properly aggregate those tutorials to meet this user’s needs? I suppose long-time wiki writers would answer: use categories and encourage tagging, while looking out for orphans. Any other ideas?

I got a great question from Tom Johnson of I’d Rather Be Writing:

I’m just wondering if you have any thoughts on the WordPress Codex, Yesterday I was looking at this Codex wondering what to make of it all. I think I want to be a contributor, but there are so many topics. It’s chaotic. The organization is like a maize. I don’t know if I should go in there with a wrecking ball and rennovate, or not. Probably 25% of it is outdated. What happens to those outdated pages? Will I offend people if I just delete things that are outdated?

Can you recommend a book or strategy for making sense of massive wikis? Where should I start? I spent a good hour editing a page of it last night that I considered critical. It’s then that I realized this is a huge project and I have no sense of direction. Any insight you can give me would be much appreciated.

With the OLPC wiki, David Farning on the Library list went through the wiki and said he found these categories. It’s quite an accurate content analysis from what I’ve seen, so I was impressed. At the same time, it also helped explain my initial wonderment at how to wrap my arms around the entire wiki – and in fact, it is barely possible to do.

1 Philosophy
2 Contributing
3 Creating
4 Curatoring

5 Projects
In progress

6 Management

Once David came up with these categories, he then asked SJ Klein, director of community content and long-time Wikipedian, if he thought the wiki needed structure.

SJ said that the wiki is purposefully without hierarchy – flat, especially for projects, to not force a parent or sibling sense for projects. He also said, however, if you have a specific tree hierarchy in mind, feel free to develop the idea in some temporary space.

So, when working on a large wiki if you have good organization ideas, set them up, and then ask for community feedback. Seems like an appropriate approach to a large wiki.

Other ideas for starting out in a large wiki environment:

While it might seem like it’s a question similar to “how do I get started on a huge writing project?” in my experience, wiki editing has some subtleties due to the collaboration and community vibe already present behind the pages. You have to work harder to figure out that vibe, and then determine your course.

For new people, there’s the whole question of getting a feel for the community so you can start to answer “who am I going to potentially irritate by editing this” and “as a newbie do I have the confidence I’m right?”

So, knowing your role within the wiki community is a first step. You might take a while to get to know who’s there, what their roles are as well, and where you might best fit in. Introduce yourself with your profile page, following the WikiPattern, MySpace – see

Just like a newbie on a writing team, find out if there’s some scut work that you can do to get your feet wet, if needed, to gain the community’s trust.

Deletions are going to bring much more wrath in a wiki situation, I would guess, so they seem risky to do to start out. If you do think something needs deletion, message or email the original author or the big contributors and ask if it’s okay to mark it for deletion. Then, mark it, and hope that someone else (a wiki admin) determines if it should be deleted.

Start small, like tagging, or applying templates. That’ll help you get a feel for the bigger picture.

Let us know your ideas for wrapping your head around a large wiki, we’d love to hear them.


Unconference in Vancouver during DocTrain West

I’m working on an unconference for Wednesday evening of DocTrain West from 6:30-8:30 (well, beer-thirty) – with only a little bit of overlap between one of the receptions and the unconferece. Please, come and participate with us. I’ll bring my XOs for demonstrations, Lisa Dyer is presenting about her DITA-wiki hybrid, and Alan Porter will talk about publishing placement (and he’s really thinking outside of the box for this one.)

If you want to attend or present, I’ve set up a wiki at

I originally installed PBwiki 2.0, and didn’t realize that decision meant no wiki-wide password or invite key like what is available on PBwiki 1.0. Woops! I truly intended it to be like a BarCamp wiki where they publish the password right on the login page. I can see why people are clinging to PBwiki 1.0 wikis now. But, I’d love to have you on the wiki regardless, so just email me for an invite.

Here Comes Everybody: The Power of Organizing without Organizations

I’ve listened to about the first 45 minutes of Clay Shirky’s talk on “Here Comes Everybody: The Power of Organizing without Organizations.” Well worth the time spent – especially for my current employer’s product set, which enables organizations to manage their data used to communicate with and connect their members with each other through event planning – all the goals that associations and non-profits strive for every day.

My favorite example, since I’m fascinated with wikis for documentation, has to do with setting up a community of practice faster than ever known in history. On Flickr, a group dedicated to High Dynamic Range photography became a popular destination and learning and collaborating connection.

Before the web, it would have easily taken five to seven years to build up the community – starting from the time when a professional photographer figured out the technique, to the time when ordinary people having the knowledge to accomplish HDR. Using Flickr, it took three months to build a community of practice, because when a photo goes up, people talk with each other, ask how photos were done, and examine the photo examples to learn. In this case, the technology became a platform where people help one another get better.

This group has no commercial incentive whatsoever, as a side note.

The community is as important as the content, a humbling thought for us writers. Just like the Architecture of Participation that Tim O’Reilly talked about in 2004, the participation of community members to generate and test content is as key as the content itself. He even states, “the fundamental architecture of hyperlinking ensures that the value of the web is created by its users.” Google Page Rank further adds to the value by including inbound links in its ranking algorithm.

On The Content Wrangler site there’s a great post asking where does user participation fit in our world? There are plenty of answers, and my interest lies in the case studies that show the amazing power of what results when users actively participate. If you’re interested in user participation and social networking, check out Tom Johnson’s interview with Scott Abel about social networking.

OLPC sxsw wiki writing

Stories from SXSWi 2008 – Attracting girls to IT

15% of people are from the northeast
15% of people left handed
15% of people in the world have no cell phone, or no Internet
And… less than 15% of computer science majors are female. [1]

This was the lead-in for the panelists and I liked the tie-ins of 15.

Since this session, I have talked to girls around the 12-15 year old range, and I completely agree with all the panelist’s observations about how girls don’t think they’re good at something, especially computers.

In this session I met Ashe Dryden and we talked about BarCamp Austin – she’s an organizer for BarCamp Milwaukee. I asked her to watch my laptop while I got a “pop” and offered to get her one too. I laughed when she asked upon my return, “Where are you from, if you say ‘pop!'” I have lived in Austin seven years, but haven’t let go of my Midwestern roots (Indiana and Ohio), where we say pop for all kinds of soda, pop, soda pop, Coke, and fizzy drink. 🙂

After the session I spoke to Clare Richardson of GirlStart about how the Austin XO user group would like to help out with their projects. One that’s upcoming is the Take IT Global showcase, where they’re working on games for the OLPC project. It sounds like they have enough XOs for their upcoming event, April 26th, which I plan to attend. They’re going to show off the educational game projects that the girls in the GirlStart program have been programming. They’re using a wiki to keep notes, collaborate, do project planning, all for the work they’re doing on their games. It’s great fun to read the game ideas.

Here are my notes from the session.

Clare Richardson – GirlStart in Austin, TX
What class in middle school did you feel smart and confident in?
art, phys ed, math, computer lab?

Free afterschool programs and summer programs.
Role models are key, role model training. Great training document available on their website. I plan to read through it for ideas on taking the XO to classrooms.

Jay Moore MentorNet
Email connection with mentors, 10-15 minutes a week.

Abby Tittizer IBM Extreme Blue
Internship program, not specific to women, for college students.

Q: What are the common misconceptions about girls and technology and getting them interested?
A: Perception is boring and nerdy and you have to already be good at it. Girls have altruistic missions.
Girls don’t think they’re qualified to do something, but boys “just go for it.” girls think that an internship means they already need to know how to do it.


  • Have girls sign up in pairs for a computer class.
  • Spend time with your kids teachers and guidance counselors to find out more about their science education, etc.
  • Boys tend to have an inflated sense of their own competence.
  • UT has a club that has a roadshow that goes out to TX high schools to help recruit.
  • They use pair programming in introductory classes.

Updated to add: There’s a great article in the NYTimes that I found through Anne Zelenka‘s links called “Sorry, Boys, This is our Domain.” While girls might not be computer science majors, they are excellent bloggers and customizers of all sorts of web and social sites. Quote: “…a study published in December by the Pew Internet & American Life Project found that among Web users ages 12 to 17, significantly more girls than boys blog (35 percent of girls compared with 20 percent of boys) and create or work on their own Web pages (32 percent of girls compared with 22 percent of boys).” Girls may have more patience and perseverance to stick to a site that requires content updates.

Wiki as online help source

A response to the question, Wiki-to-Help? on the Help Authoring Tool Yahoo Group.

One of our test engineers (and the lead developer of our company wiki) just approached me with the idea of using our company’s internal wiki as the central repository for all company material and using it to generate online help.

I’m following the discussion with interest. I, too, had a similar question asked of me from a developer when we were working in an Agile development environment at BMC Software. In that case, which was at least three years ago, the matchup between the wiki HTML output and the HTML output I needed for our particular help system just wasn’t a good fit. But today, there are better pairings, input to output. I think it’s feasible to go from a wiki to an online help system. It really depends on what output you need, and what you’re willing to do to ensure that the wiki source is worthy of publishing (tested, vetted, trusted, and so on).

I’ve been working on wikis as source for manuals, where the output is a PDF file. In general, yes, wikis are a little clumsy to work in for authoring. For example, some wikitext doesn’t understand that you want a numbered step list with images in between each step and that you want the numbering to continue after each image. So if you’re accustomed to a nice HTML authoring interface, a wiki authoring interface will “feel” like a step about 10 years back in time. 🙂

On the more interesting issue, the cultural issue (or the career issue, depending on how you think about it), I think the basis of most arguments against using wikis as source is the fear of loss of authoring control. See for the many anti-people patterns that wikis tend to foster if you don’t take steps to avoid them. I especially liked one of the responder’s comments to the list that he didn’t want to become an editor for a wiki. I think he’s right – that “magazine editor” is one of the roles you could take as a wiki-based author. You could also consider your role to be “community director” if you think you can motivate others to contribute to your wiki that will eventually be the help system. There are different roles that will evolve, and it’s up to you to figure out what role might work well in your environment (or if it would work at all). I wrote up a blog post last week about determining where your role as technical writer is most valued in the company, and building from that role.

I believe the cultural or social difficulties are the more difficult hurdle – you have to ensure that the community surrounding a wiki (those that can and will edit) is a group that is willing to work together and collaborate towards the common goal of publishing a customer-facing help system from the wiki. In a SXSW Interactive session titled “Edit Me! How Gamers are Adopting the Wiki Way” one panelist said that a core group of five editors on a wiki may be the best practice for the size of the group. This type of small number is represented and described in the 90-9-1 theory on wikipatterns.

A solution that might help you wrap your arms around the wiki as source is to set aside only one area or category of the wiki as the articles from which the online help gets generated. Again, without knowing the wiki engine you’re working with and the types of output you’d require, it’s difficult to know if a “wikislice” solution could help in your situation.

Anyway, I could go on and on (and I believe I just did go on and on) about using wikis as source for end-user documentation. I’m pleased that Sarah O’Keefe has just published a white paper titled “Friend or Foe? Web 2.0 in Technical Communication” that should be helpful as we begin to define our roles in each company and how we integrate user-generated content with our own on our product’s web sites.

I hope this information can help you build an argument for or against the use of wikis as source for online help. Please let me know the eventual outcome, and I’d love to hear your thoughts on my response.

DITA wiki writing

Building a DITA-Wiki Hybrid

Article PDF for Building a DITA-Wiki hybrid

The April 2008 issue of the STC Intercom magazine is dedicated to DITA (Darwin Information Typing Architecture).

I’m pleased that the Building a DITA-Wiki Hybrid article that I co-authored with Lisa Dyer and Michael Priestly is available online for free to anyone, STC member or non-member. The article discusses these three ideas for merging DITA and wiki technologies:

  • DITA Storm, an online DITA editor with an edit button on each page. While it’s not quite a DITA wiki, it seems like it could become one with some RSS notification and comment or discussion ability on each page.
  • Wikislices are a cross-section of a wiki such as Wikipedia, currently created with school curriculum in mind. Michael Priestly and I are working on a team to find ways to use DITA maps to manage and build wikislices.
  • Lisa Dyer has implemented DITA as a single-source with wiki as output for a documentation site housed behind a Lombardi customer support login.

I’d love to hear your comments on the article here and any other ideas you have seen for a DITA-wiki hybrid.

agile DITA

April 16 Central Texas DITA User Group meeting


Using DITA Content for Learning Content Development

John Hunt, of IBM, will give a presentation regarding the use of DITA for learning content. He’s been working on a new Learning and Training Content specialization that will be part of OASIS DITA 1.2 release. If you’d like to do a little pre-work, check out this article about using XML (such as DITA) for learning content:

A map domain for a learning object


John Hunt, DITA Learning and Training Content Specialization SC chair. John is also DITA Architect and Learning Design Strategist in the Lotus Information Development Center at IBM.

I’m also looking forward to Mike Wethington’s presentation to the DITA user group for the May 21 meeting, where he will talk about Agile development and its affect on technical communications. Mike’s the manager of technical communications at Troux Technologies here in Austin.


Technical writers and conversations

I’m continuing my musings on connected conversations and tech pubs since there were such great comments and conversations going on with it.

I had an “ah ha” moment at SXSW Interactive, when one of the social media metrics panelists Rohit Bhargava said he sees three areas or channels for measurable conversations – Public Relations, Marketing (Sales), and Customer Support.

For me, those three categories crystallized this connection: where our role as tech pubs is strongest in an organization, that’s where we might start successful conversations.

Gordon McLean’s post cites Marketing and Sales as a strong tie-in, and sure, I’ve seen that and worked in that type of environment. Marketing concepts such as Business Service Management and white papers about ITIL were the primary reason and communication idea I used when I started my blog at talk.bmc in 2005. Product documentation that helps drive sales or close deals is a great method for proving our value.

Tech support seems the best alignment for many companies, as Charles Jeter’s follow-up points out. Tech publications that drive down support costs are another area where value proof lies.

Where tech writers don’t stand much of a chance, based on my limited experience, is public relations. We tend to be a fact-finding lot, not the “spin doctor” type, nor are we necessarily prepared or educated in the ways of crisis communication. I myself cringe to think of having to write blog entries for Southwest Airlines after the recent safety fine. There’s a great case study on crisis communications at BlogWrite for CEOs – Case Study: Southwest Airlines’ Corporate Blog and Crisis Communications and reading it makes me realize how difficult it can be to blog for a company as a representative of a company.

Now, my question is, will companies pay technical writers for a conversation rather than a deliverable? Perhaps only if there are some metrics to prove worth and value.


Quadralay, a wiki-driven company

Alan Porter’s presentation at the Central Texas DITA User Group meeting talked about Quadralay’s use of wikis internally and their external wiki at

They have four wikis in operation right now, with one more to come. Back in 2003, they started their first wiki for the development team. Their company is a small one, based in Austin, and they now have absolutely every employee (with the exception of one person) having contributed to the wiki at some point or another. Currently, with their staff of 15 people, half of them contribute several times a week.

They held a brown bag training session for the whole company when a wiki for the company came out, to help people get comfortable with editing.

At their WebWorks RoundUp user forum last year, they demonstrated a proof of concept that they could take a mix of FrameMaker, DITA-XML and Word source and turn it into wiki text. I was at the demo and it has such a nice “cool” factor even if it was a simple Proof of Concept (PoC).

Another case study – they use their wiki to communicate with clients and customers on the bid and contract process, and people say it makes things go so smoothly with great communication. They use the very secure MoinMoin wiki engine and it is locked down with tight controls.

The WebWorks Services wiki:

  • used to create and track task tickets
  • offers single point of contact
  • facilitates interaction between customers and engineers
  • gives a timeline for edits on a page
  • gives them milestones and percent completion

In the next six months or so, they’re planning on a new doc site, (not yet live) to be authored in DITA using structured FrameMaker, then published to wikitext using WebWorks.