Writing Technical Policies
I’ve been interested in tech and the selection of technologies for projects for a long time. I’ve investigated how to delegate the vision for a technical project. How can we describe what really matters? How can we get teams to understand what we expect a solution should in general be capable of? How detailed can we be with out suppressing creativity? Are these policies even useful?
Recently, island.is, the main open-government platform in Iceland (run by the Icelandic government) posted a new technical-policy (“Tæknistefna” in Icelandic) for the island.is project, for public review. I think it’s fantastic that they run their tech-policy through this kind of open process, as it invites anyone who is interested to give their feedback.
I read the policy, and will probably participate directly in the review process. When reading that policy I instantly felt it was addressing things it shouldn’t, and maybe not really addressing things it should. So I decided to write about what I think such a policy should have, and the motivation behind it.
If you are a technical manager, and you need to provide a technical policy for the company, for a product or a project, these guidelines might help you. Think of it as a document the architects and programers will read, and use for guide while building their solutions.
Purpose & scope
What is the purpose of such a policy? It is to broadcast the technical vision for a specific scope, to the teams that should work with in that scope on IT-projects.
Generally the scopes are:
If the scope is a company it should be more abstract than for a project and product, but I feel such a policy should only exist for a product or project, or if the company is a product company, it could be for that company.
Different projects will have different requirements at this level, but it can still help to have an abstract policy at a company level.
When you have technical policy for a project, it can be more specific and more restricting, but at a project level it may well be that you rather opt for having multiple ADRs (Architectural Decision Recordings) that describe these project specific requirements.
First of all, such a policy should have a prioritised list of non-functional requirements (sometimes called cross-functional-requirements - CFRs).
These requirements describe the most important requirements in general for this project to succeed. To name a few, here is a list of popular CFRs (there are many more):
- Environmental impact
- Data Integrity
- Low cost of running
- Time to Market
These kind of requirements are called non-functional as apposed to functional requirements that describe a very specific part of functionality a solution should have. Functional requirements should not be stated in a technical policy of a project, as they have much more to do with the business logic of the system.
When writing a technical policy, I highly recommend to select only the CFRs that are most important for your project to succeed. Prioritise the list and write a good motivation for each, answer the question “Why do we have to have this?”. This is very important as a single word CFRs can easily be misunderstood.
This should be a list of 5–7 CFRs in a typical project. Try not to use contradicting ones, as it may make the policy hard to understand and/or expensive to apply.
This will help the team of developers to understand what kind of system they are building and what matters the most to make it succeed. The prioritised list will help the team to take design decisions as they will know what is most important.
The policy can have general requirements, to all projects it applies. In this chapter you could specify requirements for general rules on, for example how APIs should be implemented with JSON or Soap or how APIs should behave, with regards to paging and linking. Here you could also describe requirements on general audit-logging. Rules on authentication and authorisation could also be mentioned here. Requirements for Internationalisation could be presented here.
Often this kind of clause comes with links to ADRs that explain how and why these requirements exist.
The Technology Selection
So what about selection of programming languages, frameworks, deployments etc?
On the other hand it can be good to have a chapter that describes the general rules for selecting technologies. You might for example want to limit cloud tooling to a specific cloud provider, for some reason that might, or might not be stated in the policy (for example contract based reasoning). You probably don’t want to dictate things like “all solutions that have web based user interface must be built using ReactJS ”, unless it really, really matters.
It can be reasonable to mention specific tools in to the policy, but tomorrow there may be a reason to look into a new version of Angular or VUE. Similar can apply for java vs .net or oracle vs mysql. There may be budgeting reasons for technology choices. You might want to tell people to always select open-source alternative if it exists with a license you can approve of.
Definition of Done
You might want to define “Definition of done” for the scope of the policy. There you could define how a project should report on its own health, how it should scale under load, what kind of monitors are expected to be in place. There you could also specify what kind of tests should have performed done on the way, such as security audits and exploratory testing or performance testing (if required).
It’s easy to get carried away when writing such a policy, and put everything in it. So please don’t:
- Put version numbers of libraries, or libraries for that matter. Such things should live in ADRs closer to code-projects.
- Put in requirement for code-validation such as 100% code coverage with unit tests should be reached. This kind of requirement would rule out other types of testing that can also be very successful. Much better would be to say all code branches should be covered by tests, that validate that no behavioural changes in non-impacted areas have happened.
- Put in requirements that should live in ADRs, or design documents for specific solutions/products that are a part of this solution, but not applicable for the whole solution.
I feel that when while writing such a policy one should try to be not too specific. If you have many specific requirements the policy will suppress creativity as programmers usually strive to find the best solution to a problem.
As a developer I feel that in some projects there is too little to go by, possibly no non-functional requirements specified anywhere, and that leaves team-members sometimes guessing or arguing about what is most important for a solution. Sometimes we can just turn to the technical manager of the project and ask which is more important, but having access to such a policy would often answer this kind of question earlier.
A technical policy that has been created, should be reviewed and updated periodically, based on new business requirements or use cases, to be kept alive.
I also feel that the best result in building such a policy, can be reached with a team effort. When multiple developers and architects work with the technical manager to come up with the best such policy possible, and iteratively improve it in the process, then they also influence team-mates, and help keeping the policy alive.
I am sure that applying a good tech-policy will help any software project to be delivered faster, and solutions should be more aligned. Just be careful not to suppress creativity, or blend in what could be in an architectural document for a solution.