Documentation

README

Each repository should have a clearly defined and updated README.md. This is often an overlooked and neglected artifact in the source code, but it is critical to keep this as living documention.

The README file should describe everything needed to run your app locally, including the environment and dependency needs, and instructions on running local builds and tests.

- Provide a short one or two-sentence introduction to the project and explain the objectives
- Local setp (software installations, dependencies, API references, instructions to build and test)
- How to contribute back to the source code (see below section on Contributing)

Onboarding team members, opening up your repository for innersourcing and contributing, and keeping information from going stale are all important factors in keeping your application in a healthy state continued, smooth development.

CONTRIBUTING

Allowing other teams to contribute back to your source code can be a quick way to remove bottlenecks, encourage innsersourcing, and expand capabilities. Teams should maintain a CONTRIBUTING.md file to provide instructions for external teams to contribute back to their repository. Norms around external contributors generally include a branch (or a fork), CI validation, ticket auditability, and supporting documentation.

CHANGELOG

As new features or bug fixes are added, teams should keep a record changes, captured in a CHANGELOG.md. Change logs should be updated with each new version of the application, including new completed features as well as patches.