Finally I got sick with the webservice spec documents we were using at my previous employer. I searched all over the web for a document template that I could use for laying out our new web service’s API specification. I found several ones – good and bad -, but none were up to my expectations. So I decided to create a document template myself. My key design goals were the following:-
- Ease of use
- Not boring to look at.
I finally came up with a document template that I (and my colleagues) liked. Hope you find it useful too. Its created in Google Docs and shared ‘publicly’, so you can easily copy it and use it for your own projects.
See it in action -> Web service API Specification Document Template
If you are already logged into your Google account, you will see a preview and ‘Use this template’ button below:-
(To use the template, login to your Google account and then refresh this page, and you will see a ‘Use this template’ button below)
Tips for use:-
- Be consistent
- Use colors, fonts, font size etc to visually distinguish and classify things.
- Use fixed width fonts (courier, monospace etc) for showing code.
- Don’t clutter it up with too many colors and fonts.
- Managing and updating a good document is not very easy; but remember, everything worth doing is difficult anyway!
So what do you think? Like it? Where do I need to improve it?