5 ms·

I work at Twilio. Thanks for the kind words in the article. It's important to actually watch people use your documentation, to see how effective it is. The OP

I work at Twilio. Thanks for the kind words in the article. It's important to actually watch people use your documentation, to see how effective it is. The OP linked to our HowTo section as a good example of focusing on use cases. In user tests the HowTo sections are one of the least effective sections of our documentation. Most of the howtos are only available in PHP or C#, and the way they are written now makes it difficult to translate that code into the language the user would rather use. They also put more focus on working code samples than on explaining the concepts - people really struggle with understanding what happens when they get a call or a text at their Twilio number. We're working on revamping our documentation to help make this stuff more clear. So I'd be wary - the concept of code samples is good, but the devil is clearly in the details.

hrabago 14y ago
Thanks for this reply. I will be taking on an API documentation project for my team so I was particularly interested in this article, and thought the How To sections were a great idea. In my case, I don't have to support multiple languages, so that won't be an issue, but the additional insight into explaining concepts is helpful.
mtattersall 14y ago
I am actually usability testing our tutorials now, asking them to read and think aloud. It has been really helpful to see people charge off down the wrong alley if the wording is just slightly off. I've re-written the tutorials 4 times already as a result. Also because we are supporting all 7 programming languages, watching a .NET developer vs. a Ruby developer has brought up some fascinating differences of interpretation.
cjdentra 14y ago
Do you have concerns about keeping your documentation in sync with your source? I find that when I'm working with examples that if they don't work I first assume that it is me or something in my configuration. The last thing I think of is that the docs are out of sync with the example.

hrabago 14y ago

Thanks for this reply. I will be taking on an API documentation project for my team so I was particularly interested in this article, and thought the How To sections were a great idea. In my case, I don't have to support multiple languages, so that won't be an issue, but the additional insight into explaining concepts is helpful.

mtattersall 14y ago

I am actually usability testing our tutorials now, asking them to read and think aloud. It has been really helpful to see people charge off down the wrong alley if the wording is just slightly off. I've re-written the tutorials 4 times already as a result. Also because we are supporting all 7 programming languages, watching a .NET developer vs. a Ruby developer has brought up some fascinating differences of interpretation.

cjdentra 14y ago

Do you have concerns about keeping your documentation in sync with your source? I find that when I'm working with examples that if they don't work I first assume that it is me or something in my configuration. The last thing I think of is that the docs are out of sync with the example.