Comments on: You Are Frustrating Your API Users http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/ Cory von Wallenstein's Blog Thu, 09 Sep 2010 06:46:12 +0000 http://wordpress.org/?v=2.6.2 By: Gretchen Berlinski http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-263 Gretchen Berlinski Thu, 20 May 2010 07:48:40 +0000 http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-263 I am having some troubles trying to load your website bog. I have been read it(blog) many times before & never gotten something like this, but now when i try 2 load something it just takes a little while (10-14 minutes) and then just stop. I've tried with www or not. Does anyone know what the problem could be? Ask your support at hosting..And, yes, thanks for your job! I am having some troubles trying to load your website bog. I have been read it(blog) many times before & never gotten something like this, but now when i try 2 load something it just takes a little while (10-14 minutes) and then just stop. I’ve tried with www or not. Does anyone know what the problem could be? Ask your support at hosting..And, yes, thanks for your job!

]]> By: mccoyn http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-17 mccoyn Wed, 09 Jan 2008 14:01:50 +0000 http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-17 Another useful tool is to make your documentation a wiki. That way, if one person surfers for your mistakes, maybe they can do the next person a favor and leave a note about the problem. This would be useful for any kinds of mistakes or even just confusing use cases that you didn't think of when writing the documentation. Open source is famous for its wiki documentation, but even Microsoft has community content at the end of their API pages these days. Another useful tool is to make your documentation a wiki. That way, if one person surfers for your mistakes, maybe they can do the next person a favor and leave a note about the problem.

This would be useful for any kinds of mistakes or even just confusing use cases that you didn’t think of when writing the documentation.

Open source is famous for its wiki documentation, but even Microsoft has community content at the end of their API pages these days.

]]> By: Bobby The Programmer http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-15 Bobby The Programmer Tue, 08 Jan 2008 19:58:01 +0000 http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-15 Kernighan and Plauger, in their two Software Tools books, mentioned that they maintained their source code in a form that they could compile and test it, yet it would be automatically included when they formatted the book. Knuth's literate programming has a similar concept: You write a document, it includes code, and the literate programming system can extract the code, or format the document. The nice thing about his system is that you don't have to present the code in the order it will be compiled, or even keeping parts from the same file close to each other. Those the presentation and code are completely separated. Kernighan and Plauger, in their two Software Tools books, mentioned that they maintained their source code in a form that they could compile and test it, yet it would be automatically included when they formatted the book.

Knuth’s literate programming has a similar concept: You write a document, it includes code, and the literate programming system can extract the code, or format the document. The nice thing about his system is that you don’t have to present the code in the order it will be compiled, or even keeping parts from the same file close to each other. Those the presentation and code are completely separated.

]]> By: Cory von Wallenstein http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-11 Cory von Wallenstein Tue, 08 Jan 2008 15:20:14 +0000 http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-11 Excellent point, Bob. To combat those snafus, I try to add at least one complete example, no matter how trivial it is, as an appendix to the documentation. At the very least, there should be enough to show all of the relevant includes and other requirements to get up and running. Excellent point, Bob. To combat those snafus, I try to add at least one complete example, no matter how trivial it is, as an appendix to the documentation. At the very least, there should be enough to show all of the relevant includes and other requirements to get up and running.

]]> By: Bob http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-10 Bob Mon, 07 Jan 2008 23:30:45 +0000 http://www.standingonthebrink.com/index.php/you-are-frustrating-your-api-users/#comment-10 Most of the time the part that trips me up with examples is the includes and missing references. The code might be all there, but if it doesn't say "import blah.blah.collections," then it won't compile, and with just the snippet in the documentation, that's not enough to know what references are required. Most of the time the part that trips me up with examples is the includes and missing references. The code might be all there, but if it doesn’t say “import blah.blah.collections,” then it won’t compile, and with just the snippet in the documentation, that’s not enough to know what references are required.

]]>