Managing API Documentation in a Global Agile Environment

Application Programming Interfaces (APIs) are software constructs used to provide interaction with application domains. The growing trend of developing Software as a Service (SaaS) type of cloud applications has induced a proliferation of Web-based, service-level APIs. A web service exposes a set of endpoints or paths, which collectively represent a REST API that is used to access and manipulate a web resource through HTTP requests. The human and machine readable documentation for REST APIs is given in the form of contracts that require technical communication hybrid skills, such as low-level understanding of programming constructs and a concise and precise writing style.

Current software development and documentation processes tend to be integrated within an Agile environment in which products are delivered in an incremental and collaborative way. The picture can become more complex depending on how many teams and projects a certain TC needs to support and the timescales involved. Reviewing and copyediting API documentation that is part of the code base requires fast response rates, usually within hours. In this case, the TC is literally acting as an intrinsic part of the Agile team.

The collaborative process takes another dimension when both software development and technical writing are performed by globally dispersed teams. A TC might be expected to document software developed by multiple teams that reside in different time zones and also be responsible for a variety of types of documentation, that is, end-user documentation like release notes and online help, as well as API documentation. How does a TC cope with all these demands? The answer is far from simple but flexibility, the ability to dynamically prioritize tasks and to communicate effectively are essential.