Documentation Guidelines
When your product is developer oriented you need to take in to account how a developer thinks. The mind set of a developer is to get in, get the technical knowledge required to implement your product, and get out.
Thanks to the movement for writing great integration like Stripe, that let’s users integrate payments on any platform by simply copying and pasting code and not even have to worry about setting up variables, we as developers have been spoiled to a point that now we want everything handed to us… this is a good thing.
The days of having to use PayPal to integrate payments to your site are done, now we have a plethora of choices that mostly just differ in implementation since the playing field has been leveled so much that costs are practically no in the equation of choosing a service.
This is why I feel we need a set of guidelines for targeting developers to implement your services, based on the knowledge that implementation is your selling point.
1. Add a screenshot.
We are still extremely visual humans, we need to see how a code will affect our system. If there’s a representation of what I’m going to get out of following your steps, I will have a bigger motivation to do it. Show me the quan.
2. Highlight code.
It might seem like common knowledge, but there are still sites that don’t offer syntax highlight in their code. Even worst when you copy and paste a block of code and the quotes on a string are not UTF-8.
3. Group by flow.
Group your documentation by the flow of using your service. If you want to sell an item you don’t start with how to cancel a purchase. Think like the client.
4. Less is better.
Even if your service is super customizable chances are that the first approach will be just a straight copy/paste. Don’t overwhelm with options, default is your friend.
5. Stay focus.
Don’t make the developer go through pages and pages of documentation. Ruby on Rails API does a great job in their documentation by having the option of a “Show more” link that will display right below the call method the actual implementation, so you don’t have to go back and forward. Keep the focus on the steps to implementation.
6. Have steps to implementation.
Knowing how many steps it takes you to go from a to b matters, even if you got 2 steps, then I congratulate you. When something goes wrong, it’s good to be able to visually go back step by step and understand where something went wrong; any visual aid helps.
7. Specify when you’re done.
Like any good story, you have to define the end result. If everything goes as expected you should be able to see “bar”. This is taken straight from TDD behavior, you need to know what output you want at all times, or you won’t know where you need to end up.
