Foul Writer’s World

I was thinking last week about how my writing has differed from the eLearning experience of my earlier career and it got me thinking, why do we continue to do things the same way? I’ve read much about the whole Learning 2.0 movements, as well as the Web 2.0 phenomenon and I am amazed at the strides those different disciplines have made. From looking at the new 2.0 world for these particular subjects I have noticed that both terms were invented at the beginning of a new era, an alternative way of thinking and working.

So I began to think about how could documentation be moved into the 2.0 world, can it or has it already? I’m not talking about this from a technology point of view or using 2.0 technology (like wiki’s) with our 1.0 documentation. This has already been discussed by various people like Ryan’s documentation 2.0 blog post at Technically Speaking. I’m talking about this from a written/cognitive perspective. For example, should we be telling people exactly how to do what they want or should we be explaining the concepts in a hope that they understand the principles quicker and learn not to rely on the help. I would much prefer to write a simple concept driven help that will be similar for every product produced. A context sensitive help that is conceptual, where a user can read a single help page and the whole application becomes second nature. Alas, I don’t think we will ever be able to make that jump in to documentation 2.0 from this perspective, not permanently at least, because developers will continue to make difficult to use applications, user interface designers will continue to be influenced by marketing and management rather than doing what is ‘right’ for the user and it will also take organizations a long time to kick their documentation habits.

I consider the closest we have come to a documentation 2.0 solution is the embedding of Help Centers. These often incorporate instructions, tips, troubleshooting and user contributions. A good example of this would be Google’s Reader Help Center. While the help does little in describing the concepts used, what it does do is keep the help simple and relies on the easy to user interface and the common sense of the user. This sort of short focused help can only be achieved on simple to use applications. Don’t get me wrong the applications can be as complicated as you like, just as long as they are simple to use, these are two entirely different concepts that unfortunately most software developers don’t spend enough time focusing on. This can be especially difficult for documenters who work in organizations where usability, design and product management all occur between the same group of people. I’ve always believed that documentation should be part of the initial usability design, the way I’ve always thought about it is if it is easy to plan and write for, it will be easy to use. Funnily enough, just as I finish typing this post up I see a quick flash in my RSS reader of a new article by Tom over at I’d rather be writing describing the biggest failure of WordPress titled WordPress’ Biggest Mistake. Apparently that they don’t have a technical writer at all, this explains why WordPress will never be the easiest blogging platform. Talk about a funny coincidence

Does anyone else have some thoughts on which direction documentation 2.0 should head? Should it be more concepts driven, more knowledge friendly, less fact based and less procedural? Or is it just impossible to achieve at the moment?

Write me a river. It may sound like a rejected line from a Justin Timberlake song but I’m actually refering to Tom Johnson’s (of I’d rather be writing fame) new social boomarking site. WriterRiver.com

The ever busy Mr Johnson has put together a Digg clone for Technical communicators and very good it is. Or in his own words:

WriterRiver.com is a social news site for technical communicators, which means you can both submit and vote on news stories. When you submit stories, they initially appear on the Upcoming Stories tab. After a story receives 5 floats, it moves to the Front Page Stories tab.

How does it work?

All you need to do to get involved is head over the WriterRiver.com and register yourself with a suitably interesting username and password. Then just start submitting bookmarks for any stories you find interesting that relate to Technical Communication. People will then come along and vote with their fingers by clicking the Vote, or in this websites case Float, button. If the story you submitted gets enough votes it is moved to the front page. The front page will show the ?10 most popular stories, a veritable must read for any tech. writer. Don’t forget to have your say by voting on stories others have bookmarked.  

The site is in its infancy, only being two days old at the time of writing this, but I‘m sure it will blossom in to a full blown service that no tech. writer will be able to live without.

As part of my ongoing wiki experiment I have installed docuwiki. Docuwiki is:

…a standards compliant, simple to use Wiki, mainly aimed at creating documentation of any kind. It is targeted at developer teams, workgroups and small companies. It has a simple but powerful syntax which makes sure the datafiles remain readable outside the Wiki and eases the creation of structured texts. All data is stored in plain text files – no database is required.

Again like the previous MediaWiki installation I will be experimenting with the wiki and I invite anyone to come along and try it out if they want.

The wiki can be found from the link below.

http://www.foulwritersworld.net/docuwiki/

The organisation I work for are creating a new web based platform. This platform, a question creation and assessment delivery solution, is designed to be rolled out in multiple languages. The architecture of the application dictates that the translation is done on-the-fly. Translation language is predefined as a user preference. This is easy enough for the application as terms displayed are basic terms (Save, Cancel, Create, etc.,) and the UI is designed be simple and easy to follow. With the help, it just isn’t feasible to do any sort of translation on-the-fly. Automatic translation just isn’t advanced enough yet.

After spending a few days discussing with developers alternative solutions for the help we came up with a method based around the DITA framework. Help would be created in a per topic method, each topic would contain details about a specific task. The tasks would be documented in a manner that allowed them to be read independently or mapped with other topics to create a full and thorough help file when needed. All this help could then be translated.

The help, plus translations will then be stored in a database and the correct language of help displayed depending on the user profile. We have decided on a very basic display for the help, something simple like Google did with Analytics so as not to distract from the information. I’m looking forward to seeing how the outcome will work.

It has been my first proper sortie into the world of DITA. I have decided that I while I like the principles behind DITA, the current toolset leaves a lot to be desired. I’m glad that a majority of the documentation will be done in plain XML for easy translation and importing in to the database.

I’ll keep you posted on how it goes.

Tom Johnson recently wrote an interesting article about “Why Software Applications Need Product Blogs, and Why They Don’t Get Them”. While I completely agree with his sentiments I also believe that instead of blogging a good resource for the proliferation of knowledge, whether for a product or company, can also be done entirely using a wiki type tool. Wikiing, for want of a better term, can in essence be very much like blogging and in fact most wiki applications include a blogging option.

At the organisation where I work we use an internal wiki, where the various product development teams update wiki pages relating to the application and often branch these pages to include theoretical and design concepts. The wiki is used by staff, management and various outsourced resources to discuss possible issues relating to the product development. The wiki allows our organisation to communicate effectively and ensures that everyone remain in the loop. Most importantly it creates a resource that is easy to search and is recorded for all to see.

Interestingly the wiki application we use (wikispaces) also allows blogs to be created and various teams (marketing, IT, customer services) and people (CEO, Product Manager) have all created blogs to help others within the organisation to better understand their work and routines.

Unlike blogs where the only sensible method of viewing and staying up to date with them requires a “feed reader” or aggregator, the wiki pages created can be monitored and emails sent automatically when someone edits the page. This is extremely useful when your work relies heavily on specific information. In my case, progress and development ideas for products I am documenting automatically arrive in my email, without me needing to go and find out for myself it also ensures that I am aware of any changes that may have occurred to previously decided concepts.