Foul Writer’s World

I’ve been busy recently trying to develop and create API documentation for Questionmark. We have a set of brilliant Web services as part of our application that is seriously under used for a number of reasons, including:

• Documentation is difficult to get to
• Cumbersome format
• Difficult to maintain

On top of this there is no way for users/developers to add comments or suggestions to the document.

I’ve always thought the way to build a set of useful APIs is not to only get them to do the t

asks needed and well. But, get users of the API to contribute towards their fellow developers education. This has a sort of snow ball effect that as more users provide tips, tricks or advice the more engaged others will become by referring to examples, suggestions and deployment options. So that’s the plan. But to do this I first need to get the API documentation out of their existing format (RoboHelp 5 projects with over 450 pages) and in to something more conducive to collaboration. So from all the options available, I think a Wiki is the best option. Why? Because a wiki allows me to:

• Break out of the confines of the RoboHelp style we currently use
• Is easier to maintain minor updates than the RoboHelp project
• Allows consumers to add comments
• Allows consumers to add examples in the community section
• Allows consumers to communicate with other like minded people
• Easier searching

So now with the decision to move it to a WIKI made, the next step is determining what WIKI would be most capable. We currently use Wikispaces for one of our other customer based WIKIs, but I’m not a fan of this platform. I’m thinking more down the line of Confluence or pbwiki. But I’ll see which one will be easier to get approval for.

After the wiki is confirmed, I’ll have to start looking at different styles of API documentation. And trust me there are many. A personal favourite so far is the Twitter API wiki. It is clean and simple in presentation and the style they have chosen to document to APIs is non cluttered and easy to understand.

Keep posted for updates

Questionmark the company I work for have finally joined the blogosphere. However, I can’t say I have had much to do with it, but it is good that they have started to be proactive with the community of users they have and fully embraced Web 2.0.

I on the other hand have been busy beefing up the content on our customer wiki in a hope that we can build up a good presence and encourage users to start creating content as well. So I have been doing a lot of research recently in to how wikis can fit in to documentation and how to get the best out of user generated content.

The following are posts I have found of particular interest:

• Using a Wiki for Documentation and Collaborative Authoring by Michael Angeles
• Wiki docs – technical documentation on a wiki oever at ffeathers
• What Should a Good Documentation Wiki Site Look Like? by Ugar Akinci
• Wikis for technical documentation, one writer’s story by Anne Gentle
• Why wikis won’t kill technical writing at Helpscribe

I intend to write a post of my thoughts and suggestions and hope to get it up soon.

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?

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/

I have decided to start experimenting with wikis. Over the next few weeks I will be installing a few wikis for experimentation purposes.

The first wiki platform I have installed is probably the best known one, MediaWiki.

MediaWiki is a open source wiki platform that can be run using either Apache or IIS and PHP. MediaWiki is also the wiki platform that powers the grand daddy of all wikis, wikipedia.

My MediaWiki installation can be found at:

www.foulwritersworld.net/wiki

Feel free to register for the wiki and tryout the wiki platform for yourselves.

For more information about MediaWiki, check out the MediaWiki web site at:

www.mediawiki.org