Technical documentation

How we document code and workflows.

If you’re working on a task that’s missing documentation (or you think of something randomly) but you don’t have time to write it up, add a card for it to the documentation project board: https://github.com/CityOfBoston/digital-documentation/projects/1

General documentation

This (GitBook) is the place to document technical information that isn’t specific to a particular project. We should be liberal with documenting our workflows and standards, and aim for the standard that any new developer could independently find everything they needed to start working on any of our technical tasks.

pageUsing GitBook

Project-specific documentation

Any technical information that’s specific to a particular project should be in a README.md at the root directory of the project’s source files. Examples include: how a new developer could install the project locally, a list of npm/Yarn tasks... basically, anything that “should be in a README”. https://www.makeareadme.com/ is a great reference for the types of information that should be included.

Also see project specific information further down in Gitbook. The project’s page in the “Project” section of this GitBook should include a link to its README on GitHub.

Code comments

Documentation comments are super-useful! See the dedicated page for more guidance.

pageCode comments