You have great software! Your Developers have invested several years, the GUI mirrors the latest UX findings, and the functions are not only versatile but are also extremely clever.
Unfortunately, this alone doesn't ensure that the success of the software will be a slam dunk. As many customers as possible must now use this new software successfully. The usability of a piece of software includes, of course, an intuitively-usable interface, but also the seamless integration into the existing system landscape. While a maximum of one integrated tutorial should be required in order to use the interface, the good old technical documentation starts to shine (at the latest) when integrating the programme into the overall system landscape – even in this brave new world – and in the form of interface (i.e. API) documentation.
Good API documentation brings with it a boatload of opportunities: the more easily the parameters of software are accessible, the more attractive it is to integrate directly into another piece of software (e.g. from a Translation Tool, directly into the Content Management System). This is not only incredibly practical, but it also provides a real competitive advantage.
The more easily accessible a piece of software is, the more attractive it is for other Developers to build additional programmes on top of. A wide range of add-ons, in turn, increases the attractiveness of the original software.
Interfaces at all points
Programming interfaces aren't just a pretty additional feature; they're a central component of many applications.
Let's assume you're a Mechanical Designer: you've provided a web service for machine control that not only allows Machine Operators to control the machine from their computer, but it can also provide Technicians at other locations spontaneous access to the machine. Successful communication between the machine and the web service is only possible via an interface.
Let's also assume that you develop various monitoring tools (for example, temperature, wind force or precipitation accumulation). These tools can be worth their weight in gold for the SCADA (Supervisory Control And Data Acquisition) system of a wind farm; provided they can be integrated easily into the SCADA system via interfaces.
Last but not least, let's consider the logistics process of a mail order company to be the chief activity: warehouse management, product database, ordering interface and accounting software – everything has to mesh seamlessly. You can certainly try to buy all software components from the same manufacturer. But this isn't necessarily always the best solution for the individual tools. It would be better to choose the best of everything and connect it all together via interfaces.
Requirements for API-Documentation
No matter how such an interface is implemented; whether as REST API, protocol or file-oriented, the usability succeeds or fails with the accessibility of the functions. These are documented in special specification formats and frameworks so that they're readable for both humans and machines.
The central goals of interface documentation are the following:
- Explain the functions of the application.
- Explain the parameters with which the interface works.
- Explain the technical requirements for operating the interface.
- List the objects used in the application and their hierarchy.
- Provide examples of applications.
- Provide information relevant to programming (e.g. on dependencies between objects and functions).
- Explanations of the concepts used and the programming philosophy are provided, in order to facilitate the "reading" into the code.
In order for software products from a specific vendor to also pursue a common philosophy, many software publishing houses use style guides (e.g. also for the production of interfaces). Good programming style distinguishes uniformity in both philosophy and concept. As with all products, this also applies to interfaces: if I've understood the first product from a given manufacturer and found it to be good, the probability increases that I'll be able to deal with the next one faster from the outset, and I'll therefore remain loyal to the brand.
However, the Developer is not necessarily responsible for the documentation. As is widely known, native speakers don't necessarily make the best grammar teachers.
