Foul Writer’s World

Finally some movement on the documenting API stuff on a wiki. We have decided the approach, the process and how it is going to work. We have also narrowed down the possible wikis to:

• Confluence
• MindTouch Deki

Both offer good web based editing and have the optional extras we need. Now, I just need to come up with a format for the older content that everyone is happy with.

I’ve been thinking of something like this:

For example:

Anyone got any other suggestions?

I’ve finally taken the time to upgrade to the latest WordPress release and I’m liking it so far. Much better backend UI and I find it loads slightly faster.

To celebrate the upgrade, i’ve applied a new theme. I’m just trying out for now.

What do you think?

Given how the media has gone mad over Twitter and especially how celebs are using it to talk to fans I was wondering, how do you use Twitter?

I tend to use it primarily as a:

• way for keeping up with friends, colleagues and other interesting parties
• way of asking direct questions to a person or group of people
• way to follow and create Live Blogs relating to an event
• method  to crack one liner gags at my friends

What I don’t tend to use Twitter for is:

• Holding conversations with others (I prefer MSN or Skype for that)
• To market myself, products or organizations
• Microblogging (I did once, but it’s not easy to express yourself in less than a 140 characters)

How do others use Twitter?

I’ve seen some interesting ideas from the likes of Greg Pope and Sean Farrell at the Questionmark Blog about using Twitter to collect

job task information

An interesting idea, but why use Twitter? I tend to keep that sort of information up to date using Evernote on my PCs and Smartphones. However, I like the idea of someone thinking about Twitter outside the realm of a social tool. About giving Twitter a purpose other that simple social communication.

So how do you use Twitter? Please discuss.

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.