Documentation is the first touch point for those curious about new software. This is especially true for APIs, because clear documentation makes it easy to understand and use them – it is often the make-or-break point for new users. As an increasing number of people read and use the documentation for the cognitive services that we deliver in the Watson Developer Cloud (WDC), the WDC documentation team receives plenty of feedback – some positive, some negative, but all useful. We want to learn from that feedback, and improve both the documentation and the experience of using it. Sounds something like the WDC services themselves, doesn’t it? Hey, people were cognitive first! At any rate, we continuously expand and revise the documentation for the WDC services to deliver the right information, in the right way, to a variety of different audiences. To help address the immediate needs of our developer audience, we’ve rolled out documentation updates across the WDC doc set, the most visible of which are the following:
  • Documentation for each service is no longer located on a single page. It has been divided into multiple files in order to unclutter the navigation for each service. This makes it easier for users to locate specific information with minimal scrolling.
  • Documentation for each service now begins with quick-start sections that explain how to get a sample application up and running on your system or in the Bluemix environment.
New sample menu
New menu updates.
In addition to these general improvements, we’ve also rolled out new showcase applications to the App Gallery portion of the WDC docs, and technical updates to the API reference material for services such as the Speech-to-Text and Text-to-Speech services. The WDC documentation team is very agile, delivering a continuous stream of major and minor improvements to the WDC docs. And we’re not done yet! Other improvements that are in the works will better identify the information that is most important for developers – and the information requirements of other audiences. Web-based documentation like the WDC docs isn’t just oriented towards developers, but also has to deliver information for business audiences (“How can WDC services help my business?”), CTOs and technical decision makers (“How can my applications benefit from the capabilities provided by WDC services?”, “How easy is it to integrate WDC services into my applications?”, “How much does it cost?”), and many others. Watch this space for more information about documentation improvements, refinements, and expansion. We definitely want to hear from you! If you have comments or questions, please post them in the Watson forums with the tag “Documentation”, or leave a comment on this post.

Join The Discussion

Your email address will not be published. Required fields are marked *