I would to suggest you have the documentation of examples reviewed and use a checklist to see if it contains all relevant information for developers. So here is a general description of the working day of an average developer.
Every day I work using S60 3rd SDKs. I am using the APIs that I am familiar with. I follow the news about new devices coming out. The announcement Nokia and Symbian make, etc. There comes a day when a new SDK comes out or a new Carbide version. It is hyped and contains great new features which my customers will press me to use after some time. So better have a look and keep up to date. But I am wary as it may costs too much time to explore the new feature or I have to learn again another new technology which may flop later on (e.g. Qt - I am not saying it will flop - I think it is a good idea - but there are chance it will succeed and there are chances it will flop).
So you download and install (S60 5th SDK). You open the documentation. Bad user experience: it is Eclipse based (CHM allows faster and more accurate searching) and it first need to build an index to be able access the documentation. We go to "What's new".
You see "Touch UI", "Tactile", "Widgets", "Web runtime", "New C++ APIs". In "New C++ APIs" there is just a list with about 20 new APIs. You wonder what they are about. So you look for some examples. There is an examples directory so you go there.
TUIEx seem to be most interesting as it contains examples about the new features. You open the documentation for Tactile.
About this example:
The Tactile example demonstrates how to use Tactile Feedback Client API on Symbian OS application. The program shows basic ways to produce tactile feedback in different situations and some related issues that are necessary in order that everything works correctly.
1) The introduction does not explain how S60 defines "Tactile feedback" - does the device give a feedback, does it vibrate, what happens it the device gives tactile feedback? Do I first need to buy a device to discover this? The emulator did not give me any tactile feedback as far as I could see when I tried to use the example.
Basically program draws two different objects (square and circle) and a button on a screen. Tapping objects’ area or dragging them will produce tactile feedback. When objects are dragged in such position that their focal points have exactly the same coordinates, tactile feedback is disabled. Pressing button at any time will enable feedback and restore objects to their original positions. If screen mode doesn't have touch support objects are not visible.
OK - let's try in the emulator (that does not costs me so much time and I am not going to run out now to buy a device).
I have my emulator in QVGA 240x320. I can click around with the mouse. I do not see the square and circle. When I switch it to QHD 360x640 they become visible.
2) This makes you wonder. Is it not possible for a device manufacturer to create a device using QVGA 240x320 TouchScreen using S60 5th Edition? How do I see the emulator is in TouchScreen mode? When I search using Google I learn QHD is 960x540? ninth HD (nHD) is 640x360? Why does the emulator indicate QHD when it is actually running nHD?
3) Only here I discover what the exact tactile feedback is. When dragged the sqaure moves shaking and makes a soft sound. Well ... why not write this in the introduction of the documentation?
3.3 Tactile Feedback Client API usage
This section explains the usage of Tactile Feedback Client API on the example program. Feedback for square is registry based and since circle is not rectangular shape – instant feedback must be used. Feedback for button is handled by component itself. This is the case with all S60 UI components.
4) registry based? instant feedback? Because it is not a rectangular shape? Why not the same mechanism for all shapes? with all S60 UI components? Is the whole UI going to shake? This paragraph raises more questions as it answers. So where are we going to find the answers?
When using Tactile Feedback Client API, instance for touch feedback must be acquired by calling MTouchFeedback::Instance(). For square object it is stored in member variable because it is often needed.
5) Again. Raises more questions as it answers. Acquired by calling MTouchFeedback::Instance(). This is a static method? What the class supposed to start with a M in that case? M is a mixin class - not a static class. Did they modify CCoeControl to derive from MTouchFeedback? Well ... it going to cost more time as I have to find out from the source code. Well ... it actually looks to be a static class method (the name should have been TouchFeedback or XTouchFeedback?).
6) For square object it is stored in member ... often needed? Why? For the circle it is not often needed?
At first, Feedback area for square is registered initially in TactileExampleSquare::ConstructL() using SetFeedbackArea().
7) OK - look at the source again. Easy to locate. But it would be nicer if the documentation explained how big the feedback area is (well ... it is the same size and position as the square).
Square’s feedback area must be updated when square is dragged or when its size is altered as a result of a screen mode change. Feedback area updates are implemented using ChangeFeedbackArea() in TactileExampleSquare::PositionChanged() and SetFeedbackArea() in TactileExampleSquare::SizeChanged().
8) Why not use the same method in both cases?
Feedback for dragging square and circle are handled by calling InstantFeedback() in CTactileExampleAppView::Move(). It is called from HandlePointerEventL() which is usually the only place to detect dragging events. It is usually a good idea to call InstantFeedback() as early stage as possible. Especially when there are some time-consuming calculations and/or graphical operations involved. This is due to latency reasons.
9) Latency reasons are always a good excuse to put the blaim on something. It the documentation not just trying to say if you want INSTANT feedback you need to call InstantFeedback() as early as possible? So InstantFeedback() will make the object vibrate and produce a sound?
10) Also strange - I understand the view receives the pointer event, but is it not possible for the objects to move themselves? OO design means you have class with operation and object mostly can handle things themselves, right? The design "error" can easily be spotted as Move takes a CCoeControl* parameter. Maybe this is also a bit unclear to me as there is no class diagram for the example.
Since circle is not rectangular shape it’s feedback must be handled by using InstantFeedback(). It is done in TactileExampleCircle::HandlePointerEventL(). Hit detection of both objects is handled by means of MCoeControlHitTest interface.
11) Still do not understand what makes the circle so different from the square that it need to be handled by using InstantFeedback(). I decided to look at the API documentation of MTouchFeedback class. It does not state it clearly, but you can read there is two ways to provide feedback. 1) Indicate an area. 2) Indicate that feedback shall be given instantly now. Well ... something the example documentation also could explain instead of introducing speculation about what is so different between a square and a cirlce.
So this consultancy now costed 2 hours of typing and investigating. In my opinion a lot of the example documentation have the same problem - essential information missing (class diagram) - not coming to the point - first put things in perspective in the introduction - state clearly the options.
Here is a checklist for reviews to improve this:
1) Think from the developer point of view using the following assumptions:
- time is very valuable.
- the developer may not have a clue or slighest understanding about your API or technology.
- be able to introduce or make the main selling point of the API in one sentence or paragraph (the introduction is the sales pitch of the documentation!).
2) Documentation should always describe the purpose of an APIs using different termonology as the name of the API.
3) Documentation should give examples of what unique selling point this API is offering for application developers.
4) Documentation should state how this API is related / compared with other APIs.
5) Documentation should very clearly state what problem the API is solving for the developer (making it simpler; avoid writing a lot of code yourself; giving access to device features which otherwise could not be used).
6) Read your documentation and imagine what questions could pop up by a first time reader/developer and provide answers to these questions or provide links to answers.
7) Provide a class diagram and sequence diagrams.
Hope this helps. Success!