README Standards

Owned by RobLoach
Last updated: Jul 29, 2022
3 min read

Overview

For the sake of simplicity, and to reduce the need for bikeshedding and debate, this document will lean heavily on standards established externally.

When possible, the recommendations will be based on those of an appropriate authority for the type of project. For example, the recommendations for Drupal projects will implement the suggestions from drupal.org.

For anything not covered by the more specific standards, this document will fall back on Richard Litt's Standard Readme. This project has the advantage of its own clear documentation, a thorough specification, and some amount of tooling and other support.

The rest of this documentation assumes you have read the Standard Readme Specification.

Shared Recommendations

  • The "Badges" section is only recommended for projects shared outside of Kalamuna.

  • GitHub cannot automatically generate a table of contents, but there are extensions for VSCode and other editors that can do this for you.

  • The "Background" section is a good place to link to Jira/Figma/Drive resources for the project.

  • For internal projects that do not have a license file, you may treat the license section as optional.

Drupal Sites

Reference

Examples

Notes

Full Drupal sites occupy an odd space between what Standard Readme defines as a normal library repository and a "Documentation Repository". The Drupal.org project documentation standards are also geared more towards modules than full sites, so here's the recommendations:

  • Use the "Title" and "Short Description" guidance from the Standard Readme spec.

  • After that, follow the section order of the Drupal project template.

  • Combine the "Long Description" and "Background" content under the "Introduction" header.

  • Instead of the Drupal standard "Requirements" and "Installation" sections, or the Standard Readme's "Install" and "Usage" sections, create a single section called "Setup" with the subheadings (as needed):

    • Hosting

      • The URL to the primary git repository

      • The URL to the appropriate Acquia/Pantheon project (if applicable)

      • Any other relevant code/environment hosting information.

    • Dependencies

      • The recommended PHP and Node versions

      • List any non-standard Dependencies (extra libraries, databases, etc.)

      • Does the site need to connect to additional databases or services?

    • Containers

      • If the project is set up for Lando, DDev and/or another automated development environment toolset, add instructions and special notes for setup here.

      • Be sure to list any extra commands not provided by the default plugins.

      • If multiple toolsets are supported, add a subheading for each.

    • Theme

      • Which theme(s) do you need to compile to run the site locally?

      • List the commands required to compile the theme(s) for non-frontend work. (ie. how to create a production build).

      • Add the instructions for running the theme(s) in development mode, or a link to the theme's own README.

    • Other notes

      • If there is any other information required to set the site up that doesn't fit into one of the above categories, add it here.

  • After the "Setup" section, you can add an optional "Development" section to explain any non-standard actions required while developing the site. Some things to consider including are:

    • Is the config_split setup for this site odd?

    • Are there any modules pinned to specific versions, or using patches?

    • Are there any special documentation requirements for work on this project?

    • Any non-standard requirements for how commits are written?

    • Is this project using additional linting/testing tools?

  • This section acts as a replacement for the Drupal standard's "Configuration" section.

  • The "Troubleshooting" and "FAQ" sections recommended by the Drupal standards can be treated as the "Extra sections" defined by Standard Readme. From this point on, follow the Standard Readme section ordering.

  • If the site has an API, use the API section of the documentation to link to more relevant documentation. Do not try and outline a site's entire API in this section.

Drupal Modules

Reference

Notes

  • Stick to the offical template, especially if the module might be published.

  • Be sure to check out the other resources and examples listed on the reference.

WordPress Sites

Coming soon!

WordPress Plugins

Reference

Notes

  • Coming soon!

Open Source Projects

Reference

Notes

  • Make sure the license section is properly filled out.

  • Consult with the team to verify the "Maintainers" information is correct.

  • If your project falls under one of the categories above, follow those instructions in addition to the above.

Internal Projects

Reference

Notes

  • If you cannot find more specific instructions earlier in this document, then follow the Standard Readme specification as closely as possible.

  • Don't forget to check the "Shared Recommendations" section near the start of this document.