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?
-
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 ?
-
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?
Good 'see also' cross reference information. All too often when I'm using the MSDN library, the info for a class/method is all very well, but shows no awareness of typical situations when it would be used, and therefore omits useful links to other topics that are commonly related. This kind of cross reference requires the doc author to actually think - because I'm not asking for a link to the documentation for return type / parameter type of the method I'm looking at (which is necessary, but is also obviously important and useful); what I'm asking for is links that anticipate the likely uses a type / method / etc. will have, and what else a program may be doing that is related.
-
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.
>There are 10 kinds of people in the world: People... I love your signature. I used to use it all the time. Jon Jacobs This message was composed of recycled electrons.
-
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?
Examples, then more examples, followed by TESTED examples.
-
>There are 10 kinds of people in the world: People... I love your signature. I used to use it all the time. Jon Jacobs This message was composed of recycled electrons.
Thanks :)
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.
-
- 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
Great list. If I could expand on 4) Simple Samples. I would comprehensive simple samples. Break down the API into it the chunks of functionality it provides and give a simple sample for each. Make sure it compiles !! Tell me if it will fit my environment early on, I dont want to read through a ton of documentation to find that its only compatible with, for example, .Net framework 2.0