Web 2.0: June 2009 Archives

Why do I Duplicate So Much Documentation?

| | Comments (0)

I've been on many projects where I spend time rewriting content - both technical documentation and course content. It seems to defy logic because if this content is already created why should another version be needed? Shouldn't a link be sufficient? Are we only doing this because we don't know any better?

Actually I do believe there are rational reasons for this phenomenon of duplicate documentation, even if they are not fully articulated. I think understanding them could help us build models where we can truly build the kinds of community-driven efforts we want.

If I Write It, I Control It

Sounds like a petty copyright but consider - suppose you link to a site and it disappears, what do you do then? Symposium keynote speaker David Wiley had an interesting solution in using the Wayback Machine to link to an archived version, but even that may not be 100% foolproof.

Another issue of control though is consistent format. Some instruction or content may be coming from different sources, but the goal of most editors is to ensure that there is a consistent voice. For instance, the ANGEL docs are written by a group of 15 people, but the format is the same, the images use the same browser and a local goddess of grammar makes sure they are all comprehensible to the general user.

Similarly the Lynda.com online video instruction series maintain a consistent format. Although the content is presented by a number of different trainers on a number of different topics, viewers can generally be sure that 1) the training videos will be segmented into short digestable segments, 2) support files are available and 3) the trainers are going to give a rehearsed presentation. This is very reassuring if you're panicking about an exotic piece of software.

Finally, it should be noted that most do-over documentation is written is for a specific local audience. Back when I was writing blog documentation, I had to make sure that we only referenced utilities we had uploaded, included information on authentication and, of course, how to activate your Penn State Personal Web Space. This kind of customization is what leads to a lot of duplicate documentation.

I Can Do This Better!

A lot of duplicate documentation comes from frustrated users. For whatever reason, the original documentation was either not satisfactory, or maybe not even discoverable. As a result, users re-document the process (so they can perform it later). If they are being generous, they share what they know either via e-mail, a blog or even a second site.

To be honest, users are generally right. I have a case where my information on an ITS tool actually comes from the Biology department. On the other hand...user preferences vary widely, especially depending on experience. One user may want to understand a concept but not care about implementation; another may need to access all the technical details but can skip over the basics.

For instance, a lot of my Unicode doc writing arose out of the fact that what I was finding was written by programmers for other programmers. Or it was written for Windows users, but not Mac users. There was kind of gap waiting to be filled.

Today, an interesting twist is whether a video or a cheat sheet may be desired (maybe it depends on what stage you're at in the project).

Adding a Missing Piece

I think the first two pieces are the hardest to tackle, but honestly what I think most communities are interested in are collecting missing pieces, especially for complex pieces of software like Flash, Photoshop or even Microsoft Office and ANGEL. A program like Flash has a lot of options available, but not even Adobe can experiment with every scenario.

Thus, what happens is that a lot of developers work through problems on their own and then (hopefully) share what they find. Currently this happens through various social networks - large and small. A small scale version is one instructor e-mailing a tip in the same department; on a medium scale information may be shared in a users forum. The largest is probably posting on individual blogs.

The information is available, but very scattered. The question is whether it can (or should) be compiled in a more organized fashion (beyond the Google search). After all, where's the line between creativity and consitency? Who has the time and where is the reward? Are flame wars a possibility? - In some cases yes!

I don't mean to be pessimistic, but these are the kinds of questions that need to be addressed in order for any kind of community to be successful. I have participated in several joint instruction projects/communities ranging from ANGEL docs to serving on an expert e-mail panel. In each case though, I was confident of the rules of the road.