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

Other related information

• API docs
• Questionmark joins the blogosphere and updates its wiki
• Documentation 2.0
• The great wiki experiment
• Foul Writers World Wiki
• To blog or to wiki software software development?