What do developers need?
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
With regards to the documentation? I like the documentation to be easily searchable (why I usually use Google to do my documenation searching) and include examples, in a variety of languages if that applies (e.g., the documentation for some web services includes examples in C#, Java, and so on). It's also nice if the examples are low level (e.g., how to use string.IndexOf) and a high level (e.g., how to create an animated button) to demonstrate common tasks. A good couple walkthroughs doesn't hurt either. And include any administration in the walkthroughs, such as how to reference DLL's and where configuration changes can be made. Just keep in mind not everybody knows the design patterns you have in mind or come from your same background, so assume they are barely competent and help them out as much as you can. Especially with getting up and running (if that isn't easy, adoption of your API/SDK isn't likely).
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
janocho wrote:
What do developers need?
The KSS filter just exploded under the strain.
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
- Accuracy in the intellisense. 2) Appropriately named methods 3) If a object requires a complex set of objects to be created first, a factory 4) Simple Samples. Ie, If I want to know how to write to a database using ADO.NET I do not want to wade through 3000 lines of codes in a complex scenario, I just want the 5 lines. 5) Make sure your samples compile 6) Obviousness is important. Is something obviously should behave one way and behaves another, fix it or have a really really good explanation way 7) Inside joke
Need custom software developed? I do custom programming based primarily on MS tools with an emphasis on C# development and consulting. I also do Android Programming as I find it a refreshing break from the MS. "And they, since they Were not the one dead, turned to their affairs" -- Robert Frost
-
- Accuracy in the intellisense. 2) Appropriately named methods 3) If a object requires a complex set of objects to be created first, a factory 4) Simple Samples. Ie, If I want to know how to write to a database using ADO.NET I do not want to wade through 3000 lines of codes in a complex scenario, I just want the 5 lines. 5) Make sure your samples compile 6) Obviousness is important. Is something obviously should behave one way and behaves another, fix it or have a really really good explanation way 7) Inside joke
Need custom software developed? I do custom programming based primarily on MS tools with an emphasis on C# development and consulting. I also do Android Programming as I find it a refreshing break from the MS. "And they, since they Were not the one dead, turned to their affairs" -- Robert Frost
-
- Accuracy in the intellisense. 2) Appropriately named methods 3) If a object requires a complex set of objects to be created first, a factory 4) Simple Samples. Ie, If I want to know how to write to a database using ADO.NET I do not want to wade through 3000 lines of codes in a complex scenario, I just want the 5 lines. 5) Make sure your samples compile 6) Obviousness is important. Is something obviously should behave one way and behaves another, fix it or have a really really good explanation way 7) Inside joke
Need custom software developed? I do custom programming based primarily on MS tools with an emphasis on C# development and consulting. I also do Android Programming as I find it a refreshing break from the MS. "And they, since they Were not the one dead, turned to their affairs" -- Robert Frost
Ennis Ray Lynch, Jr. wrote:
Simple Samples. Ie, If I want to know how to write to a database using ADO.NET I do not want to wade through 3000 lines of codes in a complex scenario, I just want the 5 lines.
Simple samples, but not "trivial" samples. The thing I hate about a lot of the stuff on MSDN is that they often only give examples for the obvious cases. For example, if there is an API call that has several overloads, they only give examples for the ones that are already fairly obvious/straightforward, and totally ignore examples for the more interesting/obscure cases (which invariably seem to be the ones that I'd most like to see a sample for). I hate that. X|
WE ARE DYSLEXIC OF BORG. Refutance is systile. Your a$$ will be laminated. There are 10 kinds of people in the world: People who know binary and people who don't.
-
Ennis Ray Lynch, Jr. wrote:
Simple Samples. Ie, If I want to know how to write to a database using ADO.NET I do not want to wade through 3000 lines of codes in a complex scenario, I just want the 5 lines.
Simple samples, but not "trivial" samples. The thing I hate about a lot of the stuff on MSDN is that they often only give examples for the obvious cases. For example, if there is an API call that has several overloads, they only give examples for the ones that are already fairly obvious/straightforward, and totally ignore examples for the more interesting/obscure cases (which invariably seem to be the ones that I'd most like to see a sample for). I hate that. X|
WE ARE DYSLEXIC OF BORG. Refutance is systile. Your a$$ will be laminated. There are 10 kinds of people in the world: People who know binary and people who don't.
nt
Need custom software developed? I do custom programming based primarily on MS tools with an emphasis on C# development and consulting. I also do Android Programming as I find it a refreshing break from the MS. "And they, since they Were not the one dead, turned to their affairs" -- Robert Frost
-
janocho wrote:
What do developers need?
The KSS filter just exploded under the strain.
viaducting wrote:
The KSS filter just exploded under the strain.
:laugh:
Regards, Nish
My technology blog: voidnish.wordpress.com (recently moved from web-host to wordpress)
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
I very rarely use the API reference. The best thing to do is to have the methods and properties named properly. If a developer will be able to use your API without looking at the docs, it means your APIs are designed correctly. Also, any methods which are tricky should be documented well in the reference. That being said, what is more important is task based help with code examples. An overview of the API is extremely important. That helps developers get started fast.
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
Thanks for the responses so far! Sorry for the cross-posting I just wanted to reach as much people as possible. I hope I can get more people comment on this, so I can gather a good sample of data and maybe even get some statistics on this an write an article in here for the good of everyone.
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
A fast car and a beautiful lady, or the vice versa, I don't think it matters too much :laugh:
ragnaroknrol The Internet is For Porn[^]
Pete o'Hanlon: If it wasn't insulting tools, I'd say you were dumber than a bag of spanners. -
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
A massive screen, super comfy seats, lots and lots of chocolate and heavily caffeinated bevarages, great keyboard and mouse.
If the post was helpful, please vote, eh! Current activities: Playing Star Craft II. Don't bother me, eh? Now and forever, defiant to the end. What is Multiple Sclerosis[^]?
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
janocho wrote:
and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
API/SDK documentation is NOT like a woman. Don't give me the silent treatment, don't expect me to know all the answers, and above all, communicate what your (the SDK's) needs are, I don't want to have to guess! Marc
-
How about I help you, you give it 5 and I'll give it 2, Ok.
Never underestimate the power of human stupidity RAH
-
How about I help you, you give it 5 and I'll give it 2, Ok.
Never underestimate the power of human stupidity RAH
Too late, it seems it already has 3 5's. Can you give it a negative 8?
-
Too late, it seems it already has 3 5's. Can you give it a negative 8?
Damn the negative does not work, honest I pressed the -
Never underestimate the power of human stupidity RAH
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
The "old" MSDN did each topic in three parts: Purpose and Concepts ("About API"), Sample scenarios ("Using API") and a reference. I liked that style very much. Though I usually started with the the function reference, feeling lost i could refer to the other parts. The "Using" scenarios were carefully selected samples, not only demonstrating the use, but also highlighting the intentions. (Today they are proud of having a not-just-generated-boilerplate reference linking to a code snippet where it's used - whther or not that sample makes any sense, doesn't seem to matter much. But maybe they are just responding to the demands of the swarming drones of mediocrity. ) From the API: usefulness, consistency, robustness (that is, doing the right thing is easy, doing the wrong thing is hard). From the documentation I expect to point out where this is not the case. My minimum requirement for reference is a purpose of each entity (class, method, ...): why does it exist and why should I care?
Agh! Reality! My Archnemesis![^]
| FoldWithUs! | sighist | WhoIncludes - Analyzing C++ include file hierarchy -
janocho wrote:
and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
API/SDK documentation is NOT like a woman. Don't give me the silent treatment, don't expect me to know all the answers, and above all, communicate what your (the SDK's) needs are, I don't want to have to guess! Marc
As well as not having a mother in law!! :)
Three types of people in this world, those that can count and those that can't www.casserlyprogramming.com
-
I'm creating API/SDK documentation and I would like to see what matters most to developers when using an API/SDK? What is most useful? important?
how about good samples that actually work ?