What do developers need?

[Nish Nishant]

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)

[Rama Krishna Vavilala]

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.

[janocho]

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.

[Keith Barrow]

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.

[Mustafa Ismail Mustafa]

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[^]?

[puromtec1]

A developer forum!! But with an auto-ip-banning mechanism for using the words plz, codez, vb, HELP!!!, urgentz, 'assignment' or the like in order to keep out the riff raff.

[Marc Clifton]

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

[Mycroft Holmes]

How about I help you, you give it 5 and I'll give it 2, Ok.

Never underestimate the power of human stupidity RAH

[AspDotNetDev]

Too late, it seems it already has 3 5's. Can you give it a negative 8?

[Forum Guidelines]

[Mycroft Holmes]

Damn the negative does not work, honest I pressed the -

Never underestimate the power of human stupidity RAH

[peterchen]

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

[Daniel Casserly]

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

[M i s t e r L i s t e r]

how about good samples that actually work ?

[Chris Trelawny Ross]

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.

[Jon Q Jacobs]

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

[Michael Kingsford Gray]

Examples, then more examples, followed by TESTED examples.

[Tom Delany]

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.

[eslsys]

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