Automated Web Service API Documentation

Problem

The company’s Web Service API offering included only a few methods, but hundreds of discrete objects and properties. With so many objects and properties, the developer clients needed an especially exhaustive reference, in addition to the code samples and scenarios that developers always want.

The reference document, however, was very difficult to keep up to date because there was no process to trigger changes to the document when there were changes to the WSDL that defined the API. Instead, the documentation team would periodically take on the forensics exercise of trying to track down what had changed since the last update. It was a heroic effort on the part of the documentation team, but it still didn’t produce a document that was complete, accurate, and helpful, so the developer clients were still unhappy.

Goals

The developer clients wouldn’t be happy until they have complete, correct, and useful information, so we needed to:

• Institute a repeatable, automated process to streamline the creation of the reference content
• Free up the writers’ time to create the kind of content that’s best created by human beings

Solution

We started the analysis by looking at existing business processes. We wanted to find something that was already happening anyway so that we could trigger the update process without having to invent the trigger. We discovered that a “staging instance” of the WSDL file was deployed a month before the changes were generally available.

Working with a developer, we designed a script that would:

1. Parse the staging instance of the WSDL file and compare it to the generally available one. This step allowed us to automatically identify changes since the last release, without doc writers having to hunt down developers individually to remember what they added.
2. Automatically create a page for each new method, object, and property. With so many objects and properties to contend with, the standalone Microsoft Word document was no longer the best solution, so we moved to a wiki software with API support that allowed the script to create a page in the right location, using the right template, automatically.
3. Generate a report that listed all the new pages so that the documentation writer could work through each page, creating useful human-generated content. Things like the relationships between objects and properties were autogenerated by the script, which freed up the writer to add real value to the content with useful descriptions, code samples, and scenarios.

Results

Thanks to this solutions:

• Documentation writers were happier and more productive. The tedious forensics work was taken off their plate and given to a computer, which is better suited for that type of work anyway.
• SMEs (the internal developers) were less annoyed and easier to work with. It’s much easier to start a conversation with, “How can we best describe these new objects on my list?” than with “What have you coded over the last month?”
• Clients (the external developers) were able to accomplish more with the API and were more satisfied with the experience.
• The company increased revenue through deeper product engagement and higher customer satisfaction.