×

Discussion Board

Results 1 to 5 of 5
  1. #1
    Regular Contributor
    Join Date
    Mar 2003
    Location
    Helsinki
    Posts
    63

    User Comments and Examples into API Docs

    Hi,

    I hope this is an appropriate forum to make a suggestion to Nokia S60 and Symbian Developer Support teams...

    In my opinion, the current Symbian OS and S60 C++ SDK developer documentation and API reference are hard to use. Method descriptions are often very short or totally missing and there are no usage examples on the same page as the API reference.

    It would be really useful to have real working source code examples connected to each class and method description directly in the API reference or at least to have a link to sample sources somewhere else.

    If Symbian developer documentation would be better, more application development could be done for Symbian OS instead of Linux and Microsoft mobile platforms. The Symbian developers would be more productive and get their quality applications finished quicker.

    At present Microsoft has far better developer documentation and tools compared to Symbian. I am not so familiar with Linux, but I think as it is an open source platform, the need for thorough API documentation is not so important there.

    Nokia has ported the Symbian SDK documentation into many formats and integrated it into many IDEs, but still the documentation contents has remained almost the same. The usage examples are still missing and the API descriptions are poor. The sample applications are very useful, but they are not tightly connected to the API documents.

    My idea is the following:
    How about putting the API reference documents online and leave coders themselves add comments, samples and usage hints to the documentation? A kind of similar idea than the Wiki, the free encyclopedia in the net.

    I like the way PHP and MySQL have organized their online documentation. They have "User Contributed Notes" connected to the description of each function call. There is "add a note" link, where the readers can submit their own notes. Many of the notes and comments there contains very useful code examples, configuration notes and other experiences.

    See
    http://www.php.net/manual/en/ref.strings.php
    and
    http://dev.mysql.com/doc/refman/5.0/...functions.html

    I think similar interactive online SDK documentation for S60 would be a fast and efficient way of making the Symbian development easier and more attractive to the developers.

    This discussion forum is very good and I have found solutions to many Symbian development problems from here. But it requires lot of time consuming searching and it is difficult to guess the right search keywords before you know the API name. (Maybe I cannot utilize all the power of the Advanced Search.)

    Hope that the Symbian OS and S60 API reference gets better soon in a way or another and we get example codes connected to each API

    With best wishes,

    Jyrki
    Aspicore Ltd
    www.aspicore.com

  2. #2
    (Retired) Nokia Developer Admin.
    Join Date
    Jan 2006
    Location
    Michigan
    Posts
    4,664

    Re: User Comments and Examples into API Docs

    Hello Jyrki,

    Until I see the prototype I'll not commit to anything but actuallywe are planning on adding some or all of your suggestions this year.

    Still I'll pass this on, to those that are deciding what to do and how to do it. It will help them persuade people to cooperate and that this is a real world need. I see a couple of your desires and I"m not sure they are included, maybe they can be added in if they aren't.

    Thanks for the feedback !! Others may have stuff to add.

    Ron

  3. #3
    Nokia Developer Expert
    Join Date
    Mar 2003
    Location
    Tampere, Finland
    Posts
    11

    Re: User Comments and Examples into API Docs

    Hi Jyrki and others,

    it would be good to get more comments on this. Would you prefer documentation packaged with SDK/IDE or have it available online ? Or combination of these ?

    +Tero

  4. #4
    Regular Contributor
    Join Date
    Mar 2003
    Location
    Helsinki
    Posts
    63

    Re: User Comments and Examples into API Docs

    Hi Tero,

    The best alternative, in my mind, would be to have the documentation available online.

    Something like the Symbian Developer Library:
    e.g.
    http://www.symbian.com/developer/tec...cketClass.html

    But with working example code included, so that it would be easy to start using the APIs in your own program by copying pieces of the sample code.
    See e.g. Microsoft's way:
    http://msdn2.microsoft.com/en-US/lib...et(VS.80).aspx

    or Python:
    http://docs.python.org/lib/module-socket.html

    Because it is a big and time consuming task to create and test the example code and attach it into each class description in the documentation, one way would be to let the developer community to create part of the examples like e.g. PHP and MySQL have done:
    http://fi.php.net/manual/en/ref.sockets.php

    http://dev.mysql.com/doc/refman/5.0/en/select.html

    Íf the documentation were online and there were an option for user comments, the users could also add questions and comments to the other developers on a relevant page of the documentation tree.

    An online documentation could be common to all IDEs (see Microsoft's example above: VB, C#, C++, J# and JScript all at the same page).

    Much of the SDK documentation effort could be put into making more contents into the docs instead of porting and replicating the same contents into several competing formats and developer IDEs.

    (For example, Forum Nokia Technical Library and Forum Nokia Technical Solutions contain mostly the same things but in different formats. However, you don't know if there is something useful in the other, what is missing from the other, so you need to read them both. That's not productive way of coding.)

    At the moment, as the documentation is offline, developers have to search forum.nokia.com discussion groups to find users' comments, experiences and example code. The discussion group topics are organized in ad hoc way, there is no direct correspondence e.g. with the class hierarchy of the Symbian OS. So it is hard to know the keywords, by which you could find users' experiences about a certain API. Because the information is hard to find, many questions are repeating time after time.

    When you are developing a 3rd party application to Symbian OS, it is very useful to find other user's comments.

    For example, if you cannot get your program working in a way you expected, there are often two alternatives:

    1) The thing you are trying to do is possible, but you have made something wrong.

    2) The thing you are trying to do is not possible for a 3rd party developer.

    When you find other users' experiences, it is easier to come to a conclusion, why it did not work and with luck you can find also a solution from the code others have kindly submitted.

    I think that by putting the documentation online and by letting the users add their comments, Symbian OS vendors could utilize the power of the developer community in making the Symbian SDK documentation to the same level as the documentation of rivalling platforms.

    The open and self-increasing documentation must be one key factor in the success of open source tools like PHP and MySQL.

    - Jyrki

    www.aspicore.com

  5. #5
    Nokia Developer Expert
    Join Date
    Mar 2003
    Location
    Tampere, Finland
    Posts
    11

    Re: User Comments and Examples into API Docs

    Thank you Jyrki,

    I will get your comments to relevant people in our tools and documentation teams.

    +Tero

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
×