VAST SERVICE WRITING

Introduction to Vast Service Writing

In the modern digital age, services have become increasingly distributed, interconnected, and complex. Entire platforms and ecosystems are made up of many different services at varying levels of abstraction that all work together to deliver experiences and value to end users.

Given this complexity, it has become very important for service providers to document their services thoroughly and clearly articulate how others can interact with them through application programming interfaces (APIs) or other defined channels. This process of comprehensive service documentation is referred to as “vast service writing”.

When done effectively, vast service writing serves several crucial purposes. It allows service providers to define governance and policies for how their services should and should not be used. It educates and enables other developers to build upon and integrate with the services successfully. And it acts as a central source of truth about a service that can be referred back to over time as the service evolves.

In this article, we will dive deeper into the art and practice of vast service writing. We will cover best practices, common challenges, methods for structuring documentation at scale, and strategies for keeping documentation up to date as services change continuously. The goal is to equip readers with an understanding of how to professionally document complex distributed services in a way that maximizes understanding, adoption, and long term maintainability.

Defining the Scope and Purpose
Before beginning to write documentation, it is important to clearly define the scope and purpose of the vast service writing project. Some key questions to answer up front include:

What specific services or parts of services will be documented? Large platforms consist of many interdependent components, so the scope needs boundaries.

Who is the target audience? Is it primarily external developers, operations teams, product managers or some combination? Tailoring the documentation accordingly is important.

What specific goals is the documentation designed to achieve? e.g. enable external integrations, improve internal collaboration, facilitate audits/compliance etc.

What is included vs. excluded? Pure code documentation is separate. Policy, operations and architectural overviews are generally included.

How much depth is needed? Details needed vary based on service complexity and audience sophistication levels.

Clearly establishing the foundational parameters like these ensures documentation remains concise, relevant and properly focused for its intended purpose from the outset. It prevents feature-creep and scope-drift as the project expands over time.

Structuring for Scalability
Properly structuring service documentation is crucial, especially for large complex systems consisting of many interconnected pieces. A well-organized structure provides intuitive navigation and aids discoverability as documentation volume grows. Here are some best practices:

Use a consistent and logical hierarchical taxonomy to group related content. (E.g group by functional areas, phases of use, abstraction layers etc).

Provide overview/introduction documentation at each level to orient the reader within the structure.

Clearly link and cross-reference related content residing in different parts of the structure.

Emphasize discoverability with liberal use of headings, summaries, tables of contents etc.

Optimize content for keyword searchability both internally and externally (e.g. public documentation portal).

Consider standard page templates/templates with common elements like navigation.

Use automatic linking of terms defined in a glossary or common references.

With a properly structured foundation, vast service documentation can scale efficiently from dozens to hundreds or thousands of pages without losing organization or readability. New content is also easier to author and fit logically into place.

Documentation Dynamics and Continuous Improvement
Unlike code or data schemas, service documentation is never truly “done”. As APIs and systems evolve, documentation must evolve in parallel to stay up to date and useful. Some strategies to manage continuous change include:

Leverage documentation authoring/publishing tooling that integrates with code/repo changes for automated updates.

Establish pull-request based workflows for any documentation changes, similar to code reviews.

Use issue/task tracking to manage documentation backlogs and prioritization.

Conduct periodic health checks and reviews to surface outdated content needing refresh.

Integrate documentation directly with code comments, specs and contracts where possible.

Collect metrics on usage/viewer feedback to focus efforts on most important documentation.

Empower subject matter experts across teams with editorial access to maintain their areas.

Maintaining consistency and accuracy over the long term requires ongoing processes, tooling support, and cultural emphasis on documentation as a living artifact – not a one-time project. Vast services, large scale documentation remains in flux alongside the systems they describe.

Tooling and Technologies

Successful vast service documentation often leverages the right technical solutions. While simple formats like Markdown work well for authoring raw content, modern tools allow more robust features:

Documentation portals with code syntax highlighting, embedded or referenced code samples.

Schematic designers and generators to depict APIs, flows, components and their relationships.

Standards based formats like OpenAPI/Swagger for REST/HTTP APIs and gRPC/Protobuf for high performance services.

Central documentation repositories with version control, automated publishing workflows.

Search indexing and discovery of public/private documentation collections.

Issue tracking, discussion forums and commenting capabilities.

Analytics on content usage, visitor journeys, bounce rates, search query volume etc.

Integrations with code repositories, review/approval systems, and continuous integration/delivery pipelines.

Choosing technologies aligned with the overall development and operations toolchain streamlines processes like keeping documentation and code in sync consistently. Community standard formats maximize documentation reuse.