Problem
We were facing pressure to respond to more requests than our capacity would allow for. In order to maintain our output on projects we cared about, we needed to enable outsourcing by creating a process for external evaluation, however we lacked a centralised source-of-truth for our standards and practices that could be used to vet compatibility with contracting agencies. This coincided with a developer-led initiative to modernise and transfer our team documentation to a more visible, maintainable place.
Solution
We used MkDocs to create a documentation site through AWS. This was advantageous as it meant changes could be peer-reviewed in VCS, and immediately visible online when merged thanks to our CI/CD pipeline.
I transferred our prior documentation to it, and then consulted with members of staff who had experience acting in contracting roles, in order to determine what information would be necessary. These were narrowed down to process and technical requirements. At a technical level, it made sense to divulge:
- At a code-level, our technology stack, quality standards and build chain
- At an infrastructural-level, our deployment environments and data pipelines
- At a testing-level, our coverage standards
- At a licensing and compatibility level, our current active licenses and target support
Learnings
- How to begin building relationships with third-parties, and how they operate
- How to provide visibility to team practices
- How to structure a maintainable documentation hub
