Documenting supported environments
Applications and entire software systems don’t run in a vacuum; they run in environments consisting of compatible hardware and software. Such environments can encompass a wide range of elements, from infrastructure like databases and cloud services, platform requirements (e.g., browser versions and operating systems), hardware requirements (e.g., memory and CPU requirements), and even network components.
Being clear on what the compatible environments look like can help software teams, customers, and users throughout the development lifecycle (planning, development, testing, and production use) to:
understand the project’s scope
estimate the effort required for development and testing (as more compatible environments directly increase the effort)
set up development, staging, and production environments
estimate costs to develop and run the software
make a test plan
triage bugs
(customers) make purchasing decisions or formulate requirements
(users) run applications correctly
…and probably many other things.
For practical documentation, I recommend separating compatible environments into three main groups:
Tested: environments that are or will be directly used for testing, or which developers use during development. (Almost) guaranteed to work properly.
Supported: environments that you want to support but don’t have the resources to test as part of the development lifecycle. If an application doesn’t run correctly in a supported environment, it is a bug.
Recommended: the optimal configuration of hardware and software for achieving peak performance, security, and stability.
The most important category is supported environments, because it ultimately determines what is a bug. This helps users to know whether to file a bug report or software teams with development planning and bug triage. A whole lot of bug reports can often be completely dismissed by just examining the user’s environment.
Sometimes it is beneficial to warn or restrict users when the environment is incompatible. For example, streaming services will restrict users, refusing to play content in unsupported browsers. Conversely, server-side software may simply log a warning upon detecting a minor environmental incompatibility.
Documenting supported environments is practically a must-have for any serious software that ends up in the hands of customers and users, including client applications that require browser and operating system compatibility and self-hosted server software.
Tested environments help with forming a test plan. Specifically, they drive the strategy for test automation and regression testing, clarifying which software and hardware combinations must be covered before a release or deployment. Tested environments also provide guarantees to users and customers in the “If you want the software to work, use this” style. Many software libraries are tested against a matrix of various dependencies, for example.
The scope and format of the documentation are going to be dependent on your context. You might prefer text and warnings for customers, for instance, while tested environments might be simply captured by your CI pipelines and automated development environments. Regardless of the format, being clear ensures that the development team, customers, and users are always on the same page.
—Petr