Developer Experience Matters

Statement

Make it easy to discover, use, and contribute to shared code, libraries, and services through great documentation, examples, and developer tooling.

What this means in practice

Shared code, libraries, APIs, and services are treated as products with developers as their users. Friction in finding, understanding, or extending shared assets is treated as a defect.

Every shared library, service, and API has clear, up-to-date documentation including purpose, getting-started guides, and usage examples.
READMEs, wikis, and API references are maintained alongside the code they describe, not as a separate afterthought.
Common patterns and recipes are documented so developers can get productive without reading source code or asking colleagues.
Contribution guidelines are published, covering how to propose changes, coding standards, review expectations, and release processes.
Tooling supports fast feedback loops — local builds, linting, type checking, and tests complete quickly and reliably.
Breaking changes are communicated clearly with migration guidance and reasonable deprecation windows.
Onboarding a new team member onto a codebase or service should be measurably straightforward.

Why this matters

Poor developer experience slows teams down and undermines adoption of shared assets.

Developers who cannot find or understand an existing solution will build their own, creating duplication and inconsistency.
Undocumented code becomes tribal knowledge, creating bottlenecks around a few individuals.
High contribution friction discourages the team from improving shared libraries and services.
Slow, flaky, or unreliable tooling erodes trust and pushes developers towards shortcuts.
Good DX attracts contributions, improves consistency, reduces onboarding time, and accelerates delivery across the organisation.

Practices that meet this principle

Maintain up-to-date READMEs and API documentation for every shared library, service, and internal tool.
Provide runnable examples or sample projects that demonstrate common integration patterns.
Include inline code documentation (XML docs, JSDoc, or equivalent) on all public types, methods, and configuration options.
Publish contribution guides covering proposals, standards, review process, and release workflow.
Automate scaffolding for new projects and services (templates, test stubs, CI pipelines, documentation shells).
Keep CI/CD pipelines fast and reliable — treat slow or flaky builds as high-priority issues.
Version shared libraries and APIs with clear changelogs, semantic versioning, and deprecation notices.
Gather periodic feedback from consuming teams on pain points, gaps, and tooling friction.
Ensure local development setup is documented and reproducible (ideally scripted).

Validation

A project meets this principle when:

Every shared library, API, and service has documentation with at least one usage example.
New team members can set up their local environment and make a meaningful contribution within a reasonable timeframe without extensive hand-holding.
Contribution guidelines are documented, followed, and reflect recent contributions from multiple team members.
Local development tooling provides feedback (build errors, lint warnings, test results) within seconds to minutes, not hours.
Breaking changes include migration notes and are communicated before release.
Developer feedback (surveys, retros, or informal channels) indicates that shared assets are discoverable and easy to work with.

Potential blockers

Existing undocumented codebases requiring significant backfill effort.
No agreed standards or platforms for hosting internal documentation.
Limited time allocated for documentation and DX improvements alongside feature delivery.
Rapid change across services making it difficult to keep documentation current.
Cultural expectation that "the code is the documentation".