It can help to begin with a section giving a 100mi view of what the project actually is at its core. What the problem might be or what the solution is.
- Google Drive space
- Dev Slack channel
- Epic in Trello
- Spec doc
- Release plan
- End to End Testing Doc
Why are we actually working on this project? What problems are we currently facing? This is not about the architecture, merely the problem and perhaps a very high-level solution.
What buttons does the user click as they go through this? Which screens do they see? What do they interact with? Is some of it in a 3rd party app or is it all within the site? Ideally, this section should be a good basis to form a Release Plan around so we can exercise all paths that a user will follow.
This is the section with the gory details. It might help to start with a quick architecture overview such as new paradigms introduced, which endpoints are affected, which third parties are involved if any, etc. A more in-depth dive to the existing problems, awkwardnesses from existing design and overarching design decisions may also be wise.
A list of any feature flags this project is managed by and what each feature flag manages such as jobs being enabled or companies being excluded from the new functionality.
This should contain everything a new engineer should need to know as somewhere between a primer and a textbook on the project. It's best to avoid making this too dense as it should be approachable for an engineer coming to the project fresh-faced. Writing strategies for this section may include explaining each new class and how they differ from their parent classes if they have one; a story-based approach explaining the code changes to achieve each story within the spec; or perhaps even something entirely different. Whatever makes the code changes easy to understand. Screenshots of new functionality are highly recommended.
This should include code snippets, feature flags that need enabling or other relevant information for an engineer to get this project working on their local copy. This might be a code snippet for creating a new object in the database that's required or amending an existing record to better fit the new functionality.
A perfect spot to link out to generic Humio queries that reveal specific log lines for jobs written for this project, for example. Links to Humio dashboards that report un/successful events in the code are also a good idea, as well as potentially Looker links for PMs. It may be helpful to add what a 'good' Humio query/dashboard may look like and numbers to look out for. e.g. a number should be around, say, 1000, if it's over 4000, all is going to pot.
This can either be a list of issues or a link to a Google Doc with the same.