Section 1.1: API Documentation

When the term "documentation" is mentioned, most engineers immediately think of API documentation. This form of documentation is utilized by software developers on a daily basis. API documentation outlines the classes and methods found in frameworks and libraries. For instance, REST APIs are expected to come with clear and concise documentation.

Consider how often you document the elements mentioned above. Do you clarify the purpose of each class in comments? Are all potential responses clearly defined for your REST methods?

To answer these questions effectively, we must first identify the end-users of our product. If our goal is to create a framework for engineers, comprehensive documentation is essential for them to leverage it effectively. For example, JavaDoc allows the generation of documentation from comments, and every platform has its own tool dedicated to documentation.

Similarly, with REST APIs, developers must provide clients with the necessary information to utilize the API efficiently. They need to be aware of mandatory headers, parameters, user authentication, and request signing. A lack of this information can complicate the usage of the final product.

However, how does this process differ when the product is not intended as a technical tool for external users? Take, for example, a taxi-ordering application—there are no public classes or APIs to disseminate. Does it still warrant thorough documentation?

This topic sparks various opinions, ranging from the belief that code should be self-explanatory to the perspective that if the product isn't public-facing, documentation is unnecessary.

While well-structured code may not need extensive documentation, there are instances where additional comments are warranted, particularly when the code's functionality is not immediately clear. As products evolve to meet market demands, the code and API often change. For classes that may become legacy within six months, the need for documentation may seem less urgent. Yet, REST APIs typically have a longer lifespan, and new team members will eventually require clarity on how certain endpoints function and the expected response formats.

Unfortunately, not all team members may possess the knowledge to answer these questions. Properly documenting these aspects can help share knowledge beyond the immediate team, serving as a valuable resource for the entire organization. This investment not only reinforces understanding of the API but also aids other teams in contributing and allows newcomers to get up to speed quickly.

Section 1.2: Approaches and Flow Documentation

Beyond API documentation, another crucial form of documentation outlines how various components interact and communicate. This is an excellent opportunity to adapt third-party API documentation to suit our product's needs.

For example, consider the following flow documentation that illustrates how to initiate a payment request from the client to the backend, integrating a payment provider. The schema highlights several components: the client, backend, and payment provider. Each is independent yet relies on integration with the others.

Documenting approaches and flows is vital for designing the final product. It facilitates a shared understanding within the team regarding how the entire system operates—such as the payment system. Without this clarity, essential details could be overlooked or misinterpreted, like the necessity of payment verification.

Crafting this type of documentation is often more challenging as it requires both business acumen and technical knowledge. The individual responsible must possess strong analytical skills to decompose complex systems into understandable components. Always write as if your document will be read by many, even if it is intended for a small team. This kind of documentation tends to outlast the API of individual classes.

Mastering the art of producing high-quality documentation can elevate your career. By encompassing all facets of the final solution and showcasing architectural vision, such documents can be referenced at any time, making them exceedingly valuable.