Government README

All government artifacts should have some form of a README, including but not limited to:

• Projects
• Services
• Agencies
• Meetings

README 101

In developer terms, a README is a text-based file attached to a project repository.

It provides simple, clear information about a project, such as its purpose, function, how to contribute or submit issues, license and contact information. Technical information includes installation, configuration and operating instructions, list of bugs, troubleshooting help, changelog and technology used for the project.

They are usually in a .txt or .md file format (sorry, no README.pdf).

The README makes it easy for external developers to understand a technical project, learn how they can get involved.

The U.S. Web Design System, Vets.gov website and are examples of comprehensive, developer-centric READMEs.

Service driven README

While a README is typically for developer-based projects, the practice aligns with building effective government services. A README is helpful because it gives basic information without communications or public relations embellishments.

READMEs help:

• Government service teams get clarity and alignment.
• The general public understand what the service does and how it can engage with it.

They help a project or service give clarity about the service provided. They can be used as the foundational document that helps new onboarding team members, leadership and the general public understand what a service does, how to use it and how to get help when needed.

README best practices

Great READMEs:

• Include standard elements.
• Are publicly accessible, mostly text-based.
• Use plain or audience-specific language without PR embellishments.
• Are simple to understand and default to document for more detailed information.

The U.S. General Services Administration’s 18F has published helpful README best practices. Borrowing from these and other recommendations, great government READMEs include:

• Title: What the project/service is called.
• Description: A description of what the project is for.
• Contribute: Instructions for how people can help.
• Roadmap: Project timeline, upcoming enhancements/features.
• Support: Where users can get support.
• Contact: Point of contact or contact information/form.
• Maintainers: People or agency who maintains the project or service.
• Acknowledgements: List of those who have helped the project’s success.
• License: Licensing information for your projects.
• Code of conduct: Community rules of engagement.

A README is not extensive documentation or bureaucratic PDF reports. If a README is getting cumbersome, most likely it needs to be shortened and reference public documentation.

README.gov

Every government project, service, agency and meeting should have some form of a README, one easily-accessible, referential document or page that gives everyone impacted – internal and external – a place to start without getting mired in bureaucratic minutia.

As with developer projects, the government README is the foundation to good public service. It’s the ultimate culture document that sets the tone for how public servants think about working for and with people.