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?
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