The /docs directory is present in the vip-go-skeleton, but will not be mounted into a production environment when code is deployed. This makes the /docs directory useful for storing documentation about an application’s functions, features, and requirements.
VIP encourages using Markdown for files added to the /docs directory, and to update those files over time. Separate Markdown files can be created in the /docs directory to document each important part of an application.
For example, files added to the /docs directory could include:
- /docs/local.md instructing users how to run an application on a local environment
- /docs/REST.md documenting any custom endpoints an application may have
- /docs/syndication.md explaining how syndication works between network sites in a WordPress multisite application
- /docs/build.md outlining the parts of an application that get built into the final deployable application
- /docs/qa.md listing manual or automated QA tests and processes that should be run on the application prior to deployment
Creating and maintaining documentation for an application helps with onboarding new engineers, but it also helps VIP Support staff to quickly understand the moving parts or complexities of an application without needing to dig into the code. In a time-sensitive situation, a faster understanding of the key parts of an application by VIP Support can lead to faster resolutions of problems.