Writing Technical Policies

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:

• Company
• Product
• Project

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.

Non-functional 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):

• Performance
• Scalability
• Security
• Availability
• Reliability
• Recoverability
• Maintainability
• Serviceability
• Capacity
• Manageability
• Environmental impact
• Data Integrity
• Usability
• Accessibility
• Traceability
• Elasticity
• 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.

General Requirements

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?
You most likely want your policy to live longer than any Javascript framework has lived so far. Therefor I suggest you try to keep such selection out of the policy.
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).

The Don’ts

It’s easy to get carried away when writing such a policy, and put everything in it. So please don’t:

My Thoughts

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.