Using real world scenarios when you write conceptual documentation for Software Development Kits (SDKs) is a way to give your readers ideas as to how the SDK can be used and to guide them as to what APIs are needed for commonly expected scenarios. This article guides you through how to gather information about scenarios, how to simplify them in order to make good examples, and how to lead developers through which APIs to use.
When companies release SDKs, they expect software developers to use them for real applications. Unfortunately, documentation often focuses on the details of how various features of the SDK work, and developers are left to figure out if those features can be useful for solving the problems that they are working on. It's extremely helpful for developers if you can lead them through a small number of real world applications, and indicate which features could be used for those purposes.
Information on how to use an SDK for one or more scenarios should be included in the overview material for the SDK. This article describes how to gather this information and how to present it.
The first step in writing about real world scenarios is to find out what those scenarios are. Typically, SDK writers are in contact with the developers who help them to understand how various APIs function. These people may have their attention focused almost entirely on the APIs, and often they are not the best source for scenario ideas. Instead, it's the job of the marketing department to know what kind of applications the SDK will be used for. Although not developers themselves, good marketing people should have enough knowledge to give you several examples of where they see the product being used.
In addition to talking to the marketing department, it's often useful to talk to the project managers. Project managers often act as translators between marketing and development, and the good ones can understand both the marketing needs and how those needs map to SDK features.
Ideally, you should have several ideas for real world scenarios before writing the conceptual documentation. If you only have one, it can make the SDK look unimpressive. A good SDK should be able to be put to a variety of different uses.
Simplifying the Scenarios
The chances are that your customers are going to build complex software on top of the SDK that you are documenting. However, if your scenario is too complex, then it's going to be too hard for developers to follow. The key here is to take what might be a complex scenario and strip away what is unnecessary. By doing this, you boil it down to something as simple as possible that illustrates how to use the SDK features to accomplish tasks that are similar to what you would see in a more complex application.
Let's take an example from my work history. I was working for Microsoft on the SDK for Tablet PCs, which are laptops that you can draw on with a special pen. When the pen was moved across the surface of the tablet, the screen would show strokes as if the pen was actually drawing. An electronic data structure called "lnk" was created that stored each stroke of the pen. Microsoft wanted me to write an article on how you could store Ink into a database.
I sat down with the project manager and asked why it was important to store Ink in a database. He said that applications may have a lot of Ink that they are storing, and they would like to have some way to store them efficiently and be able to search on the strokes to receive only the ones that they are interested in. Databases are good at searching and returning a subset of data according to some criteria. The problem was that Ink was just a binary "blob" of information that only the SDK knew how to parse. The project manager wanted the article to explain that when you store Ink in a database, you should also store some searchable metadata that is associated with it. The metadata would contain information about the strokes that the database could easily understand, and once it found metadata that matched the search criteria, it would return the associated Ink strokes.
I asked him for real world scenarios, and he said that applications that use handwriting recognition were good examples. The application would search on a word, and the database would return the handwriting strokes that generated that word. So whenever you stored Ink strokes, you would also store the recognized word as the metadata. The database would have no trouble searching on these strings.
It seemed simple at first, but it quickly got complex as we discussed it. The problem was that when you performed handwriting recognition, you received not only the best match for what the recognizer thought you wrote, but also a list of alternates which the handwriting recognizer also considered likely to be the correct interpretation. Furthermore, the alternates matched up to the strokes of the pen in a complex manner. A classic example of this is the phrase "to get her". If written with the words close together, it might also be interpreted as one word, "together". The handwriting recognition data structure handled the fact that a best match for the first two letters might be the word "to", but that an alternative could be that those two letters were part of a longer word. It was going to be very difficult to get this structure into a relational database.
I went back to my desk and thought about it for a while. It seemed to me that handwriting recognition had the potential to obscure the point I was trying to make. The Tablet PC SDK came with a few samples, one of which was a form that that a car rental business might use to mark where on a car are visible dents and scratches. It occurred to me that if the metadata contained information about the location of the ink strokes, rather than a sophisticated analysis of its shape, that everything would become simpler. I wrote a sample that allowed people to mark up a car image with Ink, and then store it in a database, and then search for all images that had Ink in a location that the user marked. A user could look for all cars that had scratches on the front bumper, just by circling the bumper and clicking Search.
When the user made some marks with Ink and then clicked Add, the sample stored each stroke's bounding box in the database with a reference to where the Ink was stored. A bounding box is the smallest box that something can fit entirely inside. When the user made an Ink stroke and clicked Search, the sample asked the database which bounding boxes intersected the bounding box of the stroke for searching. Then the database returned data from cars with those strokes, and the sample displayed them.
By choosing a very simple data structure, I was able to demonstrate the concept of metadata in a database for electronic ink without resorting to highly complex code. The scenario of a car rental form was one that people could understand instantly. If you'd like to see the full article, it's at http://msdn.microsoft.com/en-us/library/ms812495.aspx.
Leading Through the APIs
Once you have your scenario, it's useful to lead your reader step by step though the process of writing code for that scenario. This will help developers find the correct APIs to use to get the functionality that you are describing. Use snippets of sample code to illustrate your points.
In the article that I mention above, I first led the reader through the following steps:
How to set up the database with a stored procedure that looked for bounding box intersections. This was a very simple 13 line stored procedure.
How to store Ink in the database with metadata. This involved converting the Ink into an array of bytes, calling a method to calculate the bounding box, and then storing both the array of bytes and the bounding box in the database through SQL commands.
How to search on the metadata and return the Ink. This was a simple series of SQL commands.
How to view the Ink that you have retrieved. The database returns an array of bytes, and then an API is used to convert that array back into Ink.
Each of these steps is described in paragraph form and then followed by code snippets in C# and VB.NET.
It can take a lot of work to come up with realistic scenarios for your SDK, but it's worth it. Even if they are not exactly what developers are going to build with your SDK, showing them examples will get them thinking. Keep your examples as simple as possible while still maintaining a connection to a believable scenario. Then lead your developers step-by-step through which APIs are needed to make your sample application work.