Standard for Public Code

Document your objectives

Requirements

  • The codebase MUST contain documentation of its objectives – like a mission and goal statement – that is understandable by designers and developers so that they can use or contribute to the codebase.
  • The codebase SHOULD contain documentation of its objectives understandable by policy makers and management.
  • The codebase MAY contain documentation of its objectives for the general public.

Why this is important

Documenting your objectives:

  • provides an easy way for people to decide whether this codebase is interesting for them now or in the future.
  • helps scope your own development.
  • clearly communicates to other stakeholders and contributors what the codebase is for.

What this does not do

  • Guarantee that the codebase achieves the stated objective(s).
  • Guarantee contributions to the codebase.
  • Prevent other codebases from attempting to achieve the same objectives.

How to test

There is an entry for the codebase objectives, mission or goal in the codebase documentation.

Policy makers: what you need to do

  • Add the policy objectives to the codebase documentation, for example in the README.
  • Include relevant policies which impact the community, codebase, and development like value and ethics based policies, for example accessibility or equal opportunity.

Management: what you need to do

  • Add the organizational and business objectives to the codebase documentation, for example in the README.

Developers and designers: what you need to do

  • Add the technology and design objectives to the codebase documentation, for example in the README.

Further reading