Objective: The purpose of this document is to establish a set of guidelines for persistent inter developer communication of critical data related to various aspects and components within a given system.
Success: In order to consider this project successful we will need to ensure that every major system component has a clear document that defines the expected behavior as well as examples use cases to assist future developers with understanding the operation of that component.
Abstract: Thorough and accurate documentation is paramount to the success of any development project. This document not unironically establishes the foundation for the team to produce reliably comprehensive documentation of the code and systems produced.
Resources: The best way to consolidate the documentation is to include it directly in the repository as markdown files in a docs directory.
Requirements: There a number of factors worth considering for determining the requirements of documentation.
- Location of documentation
- Hierarchy of the documentation
- Scope of documentation
Location: Documentation organization is dependent on a few factors. The easiest is to utilize the docs directory within the repository root. The advantage of building documentation in the repository as a solution is that as changes are introduced a merge/pull request will be required to release the docs into the master branch. This will insight discussion about the clarity of the docs ensuring that the team collaborates on the best fit for the us as a whole.
Additionally documentation should be localized to the system or entity it is MOST relevant to. What this means is that the main app repository should contain all of the documentation related to the repository itself. Whereas the documentation relevant to a specific plugin should reside within that plugin’s root directory. Once again theme related documentation should reside within the appropriate theme directory.
Hierarchy: The following is an example of the documentation in practice. Make careful note of that the markdown files are CAPITALIZED and snake cased by dashes but the suffix is lower case. It is very important that you DO NOT use underscore or space characters in your files or directory names.
The following images are examples of the expected filesystem hierarchy.
Each docs files system hierarchy may include an images subdirectory where ALL of the images referenced in the relevant markdown documentation should reside. This ensures that these images are part of version control and easily managed. You must ensure that any security sensitive data is thoroughly blacklined and obfuscated in the images.
There is an additional convention that the README.md file functions similar to an index.html. Each read me file should function as a table of content and include a detailed description of each linked file. For instance if you have access to the Haymarket Media GitLab then you should be able to see the following README.md files:
Scope: Finally it is important that documentation is an ongoing project. You are never done with documentation. Every time we update code there is potential that the documentation will need to be modified and updated accordingly. Every ticket in Jira should include a requirement to review and update the documentation. It is imperative that every member of the Haymarket Media Engineering team take every opportunity to evaluate and update each projects’ documentation.
Summary: The the final aspect of these efforts should be to ensure that links to all of the appropriate document segment are properly noted here on the engineering team site. For instance if you have drafted a document related SSO then ensure that you add the appropriate reference pointing this on the SSO page of this site. This will ensure that all of our documentation is searchable from this central library no matter where it is located. For more information refer to the documentation index.