Every now and again you need to hand something over (code, thingamabobs, whatnot) to someone. At these times it can be good to have a checklist to go through. This is the list that I tend to use. All points are optional and users should strive for good enough. I've based it on architectural views as defined by Kruchten and others (C4 or some other scheme will work just as well).
|An overview of the major business cases that motivate the existence of the solution.
|Our customers must be able to make "claims" when they receive a defective gizmo from us.
|Conceptual Model and Processes
|Walkthrough of the conceptual model that is used in the solution. This includes the various business entities and the processes involved.
|Entities: claim, receiver, product
Processes: make a claim, close a claim, refute a claim
|A walkthrough of the functional view and the use case view with one or two typical use cases and also the more complex use cases that need to be explained in more detail.
|As a customer I can create a claim, list my claims, show claim etc.
|Everything one needs to know to develop the thing:
- components, modules
- integrated systems map
- information flow map
- integrated dependencies (DBs)
- development environment (tools, repository etc.)
- environments (dev, test, prod)
- deployment process (build chain, ci/cd etc.)
- software/support systems used
|Classic three tier architecture, MVC pattern in framework X. We also call out to the CRM system when doing ...
Usually IntelliJ + git
Wiki for documentation, JIRA for issue tracking.
|A detailing of the execution model of the solution such as threading etc. with a concentration on the hard stuff.
|The "GizmoService" is single threaded since it has to process the "GadgetJobs" in sequence and order must be maintained.
|A description of the physical environments available (should be correlated with environments in the development view) and what they contain.
|Deployed to AWS EC2 instance, with ELB and CloudFront. Separate configuration for "test" and "prod".
|Quality Requirements, Constraints
|A description of the quality requirements and possible constraints and how they are achieved:
- availability (SLA:s etc)
- reliability (fault tolerance, backup etc.)
- configuration management
- licensing constraints
- legal constraints
|A description of the operational view, how the day to day work goes, involved organizations and workflows, and how maintenance and support are performed.
|We handle development and deployment but the "ops" team handles uptime, restarts, OS updates etc. Incidents come to us first and then handed over to ops if it's of a low-level nature...
|Either an export of source code, docs etc, or access to SCM etc.