Slashdot Mirror

← Back to Stories (view on slashdot.org)

HOWTO Document and Write an SDK?

Posted by Cliff on from the kitting-it-out dept.

jmwmit asks: "A startup that I am working with is looking to write its first SDKs - one public for community developers and one for 3rd party commercial developers. What is the Slashdot recommended or preferred format for SDK documentation, both the code APIs and the general docs? What great SDK examples have people used in the past and would recommend as good models? What do Slashdot developers consider absolutely necessary features in an SDK, regardless of the application?"

4 of 78 comments (clear)

  1. What helps me by secondsun · · Score: 4, Interesting

    What makes a good SDK is decent documentation and design. What makes an excellent SDK is well though out designs and very detailed documentation. Code examples, comments, descriptions of functions functions, parameters, and return values.

    Sun has done a wonderful job with java and documentation. The only thing that I would like to see added to it would be links to items that reference each function/object.

    A project that has done an awful job at documentation and design is Squeak. There is little documentation and almost every function imaginable is in the Object superclass.

    --
    There is nothing wrong with being gay. It's getting caught where the trouble lies.
  2. Documentation formats by n1ywb · · Score: 2, Interesting

    You need to use a documentation framework to automate the process, unless your SDK only has one or two functions. I like Doxygen a lot, it's pretty easy to use and works with lots of languages. JavaDoc or PerlDoc, etc are good for specific languages. Html is a fine file format for the final output.

    --
    -73, de n1ywb
    www.n1ywb.com
    1. Re:Documentation formats by Anonymous Coward · · Score: 1, Interesting
      PDF is awful. It's not cross platform, unless you mean that you can crash every platform that it supposedly runs on.

      I use Linux at work, and Adobe's version of Acrobat reader for Linux is several years out of date. It very frequently crashes X altogether.

      An open standard, like HTML (with intelligent CSS which will allow you to print well), is far better, and there is no reason that a halfway decent CSS guy can't make HTML look very good for printing too, and if that HTML was generated from XML, then it is easy to output the documentation in many other formats too.

      PDF is a dead end.

  3. Definitions AND examples by samjam · · Score: 4, Interesting

    You need good examples to SHOW what your definitions mean.

    You need good definitions and specifications so developers can extend the given examples to their own situation.

    Each new class of capability for a given module will need some examples. Too many trivial examples and not enough meaty examples driver developers mad with rage.

    If your SDK has well defined uses, tell a story of a developer writing and refining some code for a given purpose, so the reader can see how and why the more subtle points of the APIs are important.

    The PERL 4 Camel book is a good example of this.

    Sam

    --
    blog.sam.liddicott.com