READMEs and Documentation

READMEs and Documentation

All Cantilever repositories should have a README (this is a newish policy so many currently do not). The README should explain:

  • Briefly, what the project is for
  • How to install the project locally (including the acquisition of a database if needed)
  • How to deploy the project
  • Any development quirks or gotchas to look out for (how to turn off or on a CDN, for instance)
  • Link to the relevant Dev notes

You can use the TextExpander shortcut `tereadme` to generate one.

All Cantilever repositories should also correspond with Documentation. The Documentation should include information about the project which non-developers might need. Only developers need to know how to deploy, but non-devs might need the staging URL, or the browser support.

It should include data like:

  • Overview of the project. Who is the client and what are we doing for them?
  • Relevant URLs to staging/dev environements, CMSes, etc.
  • Link to the repository
  • Info on hosting and CDNs
  • Info on DNS for the client’s domain
  • Info on browser support requirements
  • Info on standards for development (According to our dev standards rubric)

The body of the documentation should follow our standardized format which you can generate by clicking "New > Documentation" on the Site Documentation table.

This format includes:

  • Global
  • Pages
  • Behaviors
☝

More detail to come on the above and how they work.