Minimum Viable Paperwork (part 1) – public sector tech documentation for governance
If public sector bodies often suffer from documentation problems, it’s not because they don’t spend time on it
Software documentation is a problem. Deciding when a system is stable enough to start documenting it is tricky – as is determining when it needs to be updated. And both operations impose considerable overheads: time spent documenting old code is time that can’t be spent fixing, replacing, or extending it.
Unsurprisingly, then, managers and readers of the Agile Manifesto often downplay, or even eliminate, the importance of documentation. Only for their hapless developers to discover that the only thing more time-wasting than generating excessive documentation is not having enough.
What the public sector wants – and what it needs
This balancing act is even trickier with public sector systems. Government applications face higher levels of scrutiny, and need to demonstrate compliance with a wider range of regulatory and legal requirements, than the private sector typically does. Also, contemporary realities in the Civil Service – budget cuts, hiring freezes, and a reliance on subcontractors – mean that technical documentation needs to be more comprehensive than ever before. Manual handovers and extensive onboarding might not happen and they can’t be relied upon to ensure critical knowledge isn’t lost. It’s also very likely that teams are assigned to maintain, upgrade, or refactor software that they’ve never seen before.
So what follows, is a 2-part series on how to ensure public sector bodies have the software documentation they need to run their services, both now and in the future.
This first part looks at effectively managing the information needed to support public sector compliance requirements – the documentation needs the public sector is most concerned to meet, and that answer to clear and explicitly stated demands. And the second will discuss the extra information needed to guarantee service continuity and maintainability over the long-term – areas the Civil Service can be prone to deprioritise, or simply lack awareness of.
Documentation for governance in the public sector
If public sector bodies often suffer from documentation problems, it’s not because they don’t spend time on it. They do – probably much more time than comparable private sector organisations. But this documentation serves a different purpose and is oriented towards a different audience from most software documentation produced outside government departments. It’s generated to make it past governance procedures managed, for the most part, by internal review boards. This extreme emphasis on gating is what makes public sector documentation different from that of other organisations. And, unless it’s managed well, it can suck entire teams into a recurrent paperwork vortex that’s difficult to pull out of. Navigating this governance whirlpool effectively involves paying attention to 4 factors that aren’t necessarily obvious about Civil Service procedures and that are sometimes actively obscured by them.
It’s not about the forms
It’s tempting to believe, in a Civil Service context, that preparing for gating will consist of filling out a standardised form. It’s even possible (and in fact likely) that a helpful civil servant will dig out an old document submitted to review for another application, and suggest that this is the necessary form.
Unfortunately, this is a red herring. While such a document will certainly be helpful for reference, or to suggest a particular approach to the problem, forms in the Civil Service are evolutionary– old ones die away and are replaced by new ones. Also, applications and services differ markedly from one another. Questions relevant to one might not be to another. And the kind of answer provided for one app – a given diagram type, for instance – might not make any sense in relation to a different one. Because of this, it’s perfectly possible for different individuals within a department to come up with different forms or sample documents, each of them believing that theirs is the template to be followed.
Focus on fundamentals
So instead of looking for the perfect sample document, focus on what it is a governance board needs to know for the application under review to pass gating. Broadly speaking, there are 4 main headings.
- All applications are assessed against the Service Standard
- They need to demonstrate adequate security
- Data privacy needs to be respected
- Applications need to be accessible for end users employing assistive tech like, for example, screen-readers
You can expect your application to be rigorously assessed to a high standard for each of these headings. While documents created for other applications can provide helpful pointers for what information is considered most relevant to each rubric, the likelihood is that they will also contain a great deal that isn’t directly relevant and should be excluded. Conversely, you’ll need to talk to a wide range of stakeholders to ensure you’re capturing all the necessary information and aren’t overlooking anything.
The other reason that governance documentation can’t, or shouldn’t be, about the forms is that forms have extremely low visibility. Once they’ve been submitted to the review board they tend to disappear from view entirely, and they then no longer act as documentation for the wider unit or department. Instead of working to create a single complete document in the first instance, you should focus on assembling all the information relevant to the above headings in one widely available and – eventually – well structured directory. This means that if you do have to fill out a form, or create a new one, you’ll have a knowledge base from which answers can be cut and pasted, or adapted as needed.
Start with deployment documentation
When you’re starting the governance documentation process, scope can be hard to determine. What’s relevant? What’s not? How large a technical estate are you trying to cover?
A sensible place to start wrestling with these questions is assembling an inventory of deployment information. What environments and which platforms are in use, and deployed to what IP addresses? What cloud services are being used for hosting, and how are they configured? What CI/CD processes are in place? What repositories are being used?
The advantage of taking deployment information as your starting point is 2-fold. First, as well as being a prerequisite for basic security procedures such as penetration testing, it provides necessary context and a basis for any in-depth questions you’ll need to answer later. Secondly, such information is likely to prove useful to your team even in the short-term. You’ll know you’re done when you’re in a position to write a comprehensive runbook for your service.
Then – do it. Even if they didn’t ask you for it, your team will thank you for it.
Link, don’t type
Once you’re past the initial hurdle of collating all the deployment information, you’ll be faced with a range of very widely scoped questions: Are your services reliable? Are your cloud services secure? Are you developing in an Agile way?
At first, such questions seem daunting: what kind of evidence would you need to assemble to prove Agility? Sprint plans? Retro boards? What kind of test coverage do you need before you can declare your application ‘resilient’?
Fortunately, the answer in a Civil Service context is more straightforward than that. These are questions to be answered in terms of policies and the people responsible for enforcing them. If your department has a declared policy (as it almost certainly does) of using Agile development techniques, then all you need to do is link to that declaration, and there’s no need to produce your burndown charts. Similarly, you don’t need to write your own pen tests for your cloud provider – but you will need a statement of their policies and the guarantees they provide for their services.
Documenting for accountability
Remember, the review board isn’t approving your service in retrospect. It needs guarantees about the operation of the service in the future – about how you plan to deal with evolving needs, service outages, and so on. For that, it needs declarations of intent, and the names of the people responsible for carrying out those intentions, more than it needs proof of work already done.
But, even if the Civil Service exists to craft and implement policy, tracking it down won’t necessarily be easy. Any significant application is going to be governed by a wide range of policies spanning legal issues, service design standards, support requirements, and so on. Get to know the org chart for the department you’re working with well, and be prepared to spend a lot of time emailing people. And, as with everything else related to governance, make sure you store the links to the relevant policies and people responsible in a location that’s accessible, and visible, for everyone who might need to be aware of them.
The documentation definition-of-done
One of the nice things about focusing on documentation for governance is that the definition-of-done is very clear – you’re done when the review board says you’re done. As soon as they’ve stamped your application with their seal of approval, you can move onto the next phase. And if, as recommended above, you’ve assembled all the information the board ended up requiring into a widely shared and visible space, you can have confidence that the next gating process – when you enter another iteration, or move to wider release – the process will be much, much less onerous.
Readers from an engineering or development background, might, however be flummoxed by this particular definition-of-done. Is that it?, I hear you ask, runbooks and policies? But where’s the user manual? The entity relationship diagrams for the database? Where are the system dependencies specified? Where, in short, are all the documents that are needed for a developer or other technical person to actually do their job?
The answers to these questions form the subject of part 2: documentation for engineering.
* featured image by Pixabay