Weekly Digest for Sunday 24th May

I’ve now spent the last 10 weeks working from home. I’ve been really productive but do have to watch a couple of things. There are little breaks in my day at the moment. Back to back meetings/calls and no gaps. You miss the walking between meetings, talking to others. It’s full on, one topic to the next. The other thing to watch is tiredness. Feeling more and more tired as the week goes on and that’s despite a daily walk to try and recharge. Still, I’m one of the lucky ones so shouldn’t complain.

Glasgow city centre during lockdown

As the UK starts to unlock I can now see unfolding in front of me why Sturgeon said weeks ago that when to unlock and how will be really difficult. Scotland’s leaders have been far more clear and effective from what I can see. That doesn’t let them off the hook as care homes, testing, PPE and late lockdowns are all their responsibility too. However the mess unravelling in London and Johnsons defence of Dominic Cummings seem like idiocy after what the UK has been through, all summed up in this now deleted tweet.

Now deleted but sums up the views of many

How the world views Britain

While the politicians try to kid us that Britains Covid-19 response has been world beating it’s easy to find alternative views. The New Yorker calls it right – a disaster.

Patients Don’t Die Alone

This Buzzfeed article provides comfort to so many that their parents, family or friends are not dying on their own.

The Joy of Sets

Thanks BBC for another great set of video conferencing backdrops. Something for everyone here.

Scunthorpe Sans

Is this the best font ever? Scunthorpe Sans blocks any use of profanities…apart from Scunthorpe. Brilliant.

Mad Max:Fury Road

Fury Road is still an amazing watch. This article brings together many of the cast and crew who talk through just how difficult it was to make.

Tenet

Nolans new film gets another trailer that tries to explain what’s going on. More surprising…still aiming for cinema release later this year.

The Miracle Sudoku

Shared widely so you may have seen this but if not then settle down for an enthralling 25 minutes of Sudoku. Best watch this week.

Magic Keyboard for iPad Pro

When Apple announced 2020’s iPad Pro’s I had zero interest in upgrading from my 2018 model but I really wanted the Magic Keyboard. So it was with some relief after reading the blurb about the new keyboard that it also worked with my 2018 model. It was due out May but ended up launching in April. Instant purchase even though it cost £349. For a keyboard.

The one niggle I had was the lack of any mention of weight on the Apple website. Apple is really good at listing weight spec’s and shouting from the rooftops about thinness and lightness…unless it wants to keep something hidden.

iPad Magic Keyboard

When the keyboard finally arrived I was surprised at the small packaging. I opened the box, took out the keyboard, ripped of the packaging and my first reaction was…this is pretty heavy. Heavier than iPad Pro heavy. Uncomfortably heavy. Mmmm. I then opened the keyboard and the hinge mechanism felt stiff and awkward. Mmmm. Not the best of starts and one of the few products I’ve bought where my immediate thoughts were this is getting returned.

I then snapped on the iPad Pro and I do mean snap. The magnets really grip the iPad in place. Opening and closing the keyboard with the iPad Pro attached was initially awkward. Unlike most devices of the last 20 years, the weight is in the top and not the bottom. Usually you lift open a light screen in a laptop. The iPad weighs more than just a screen and is thicker so it feels counter intuitive. However after a couple of days it feels fine and you get used to finding out the convenient ways of opening and closing the keyboard.

Those initial impressions were just over three weeks ago so I’ve had plenty time to pull together some thoughts. First, the positives:

  • The keyboard is great. A real step up from the Smart Keyboard folio, the keys have proper travel and are also backlit. Far more comfortable to use for extended periods. The base is rock solid too and doesn’t flex at all when typing no matter the surface it’s on. Didn’t realise how much I missed backlit keys until I got this keyboard.
  • The trackpad although small is a great addition to the iPad. Coupled with the new cursor support it makes text editing far easier and app’s as they add support take on a new feel. Only time I notice the size is vertical scrolling. One oddity is that the trackpad is a return to a physical click rather than the haptics in the Magic Trackpad. I also found it better to visit Settings > General > Trackpad and increase the tracking speed.
  • The trackpad supports a nice range of gestures that are well worth getting to know to help with usability day to day.
  • Love the floating iPad Pro. The viewing angle is the same as the Smart Keyboard folio…and I think I’d have liked another 5 degrees or so to tilt it back but I’m being picky. Now that I’ve got used to top being heavier, it’s easy to use and the hinge is super strong and doesn’t flex.
  • One aspect of the Magic Keyboard is you can’t fold the keyboard around the back of the iPad so I’m taking the iPad off the case more often than not. Never did that with the folio…and it makes for a more comfortable reading/relaxing device that way too.
  • Taking the iPad off the keyboard can be done with one hand like most have said but I usually hold the keyboard and pull off the iPad. The magnets are really strong and the photo below shows just how many are being used to snap the iPad into place. There’s also a lot of engineering in the keyboard and hinge mechanism.

X-ray of the Magic Keyboard thanks to iFixit

There are however a few con’s to this new design that are worth considering.

  • For sketching there’s no perfect angle. Would have liked somehow to get an angle of around 170 so you can sketch with a bit of weight behind it but unless you turn the whole keyboard over….which looks ridiculous…then there’s no real solution. Maybe v2 in a couple of years time will address this.
  • The USB-C while useful charges at a slower rate than if you plug directly into the iPad which is a shame. It also is a charging port only – no accessory support which is a bummer.
  • It does make the overall iPad Pro a lot heavier – up there with laptop sizes so you may want to think through what you really want from a mobile device before going down the iPad Pro + Magic Keyboard route.
  • At £349 it still feels really expensive. Even £249 would feel expensive.

Should you buy one?

If you do any typing on the iPad Pro then yes pick one up despite the price. If you want the iPad to be more laptop like then it’s another yes. However the combined price would get you a cracking laptop so it really comes down to what you do day to day with your laptop or iPad and whether the Magic Keyboard add’s value.

The Magic Keyboard has really improved the way I use the iPad Pro. I could argue thats its transformational. The keyboard and trackpad coupled with the software changes in iPadOS to add cursor support really do add another dimension to the iPad. Cursor support has only been around for a few month but it feels so natural in iOS and so well integrated it feels like its always been there. The keyboard looks and feels great, which it really should for the price, and if you are making use of your iPad for an hour or two a day I’m sure you’ll like the Magic Keyboard as much as I do.

Weekly Digest for Sunday 3rd May

Still here. Still working from home. Hope everyone is doing their best to get through the Covid-19 crisis as safely as possible. I’ve been keeping the daily walks going and last weekend popped into Glasgow city centre. I couldn’t believe how quiet it was. While my local area is busier as people do their exercise the city centre was deserted. Nothing opened, little use of public transport. No rough sleepers. There were more police visible than anything else. No cars and the few cyclists had the run of the streets – why worry about the one way system when there is no one around. Does make you wonder what our towns and cities could be in the future when you factor in the climate challenge we face.

St Vincent Street in Glasgow during lockdown. This was middle of the morning!

Working from home has become a bit relentless. Call after call with little to break the day. Taking a few days off soon and also counting my blessings as I’m lucky. Still in a job, still productive, still healthy. My fortress of solitude is quite nicely setup now although thinking about a new office chair to make the long days that little bit more comfortable.

Home office doubling as the only office – some smoothing applied to protect the innocent!

Comparing Stats

We are told by many many people (politicians mostly) that you shouldn’t compare stats across countries when it comes to Coronavirus. I even nodded my head in agreement reading this article from David Spiegelhalter in the Guardian that it will only be at the end of the crisis that we’ll see just how badly each country has done in dealing with the pandemic. But then there are some stats that you just can’t ignore:

China Coverup?

With much of the world hitting first wave peaks, attention is now turning to how Covid-19 originated and could China and WHO have done more in January? This Wired article focuses on the information disappearing before our eyes as China tries to re-write recent history.

Getting It Right

Many countries have worked hard to control coronavirus. One who locked down early was New Zealand. While many countries have lessons to learn, if we do hit second peaks later in the year I hope our politicians look at the actions taken by the likes of New Zealand and are quicker to act.

Lockdown Photography

I’ve done precious little photography over the last two months – loving the lockdown photo project by Christopher Swan. Great images and also many places I recognise around Glasgow and also where I work. The glamour of South Street.

Watch your back

With so many video calls and Zoom traffic booming, video backgrounds are now a thing. Couple of options if you want to jazz up that call. Studio Ghibli have released a set of great images from some of their best creations and Got Your Back have an ever growing set of suitable…and not so suitable backgrounds. Choose carefully!

Love Bug

Anyone remember the I Love You virus that spread in the early 2000’s? The author has finally been found! I still remember someone at work clicking on the e-mail and spreading it even though we told him not to….but I got an e-mail from such and such that said I Love You. Doh. Social engineering is a powerful drug.

iPad Keyboards

Great article on the history of iPad keyboards. I’ve been using a Magic Keyboard for a couple of weeks and I’ll post my thoughts soon but as the article shows there’s been a lot of changes in the last decade.

Spaceship You

Important video for all of us during the lockdown. Spaceship You gives some great advice on how to get through the next weeks and months. Find 10 minutes to watch this.

1 Pixel Wealth

When you hear about millionaires and billionaires it can be hard to imagine just how much money that really means. 1 Pixel Wealth does a great job in highlighting the inequality in the world right now. Keep scrolling!

Jukebox

This is pretty amazing. OpenAI have released an AI Jukebox – give it an artist and genre and it will generate new music. Some of the results are spookily good.

The Best Sporting Video Games

The BBC have put together a top 50 sporting video games list with comments from loads of people about why a particular game is important and needs to be in the top 50. So many great memories in this list.

9 Eyes

What a time sink this is. 9 eyes is named after the Google Maps camera module that sits atop cars, bikes…even people to take new Google Maps imagery…and has 9 cameras. This site is full of the weird and wonderful images that Google has captured. Some are funny, some weird, some seedy and some a snapshot on everyday lives across the world. Addictive.

Weekly Digest for Monday 13th April

We’re now into week four of the UK lockdown, and week five of me working from home. This new normal will be with us for months. The daily death tolls are horrendous as is pretty much all news. But look on the bright side…even dogs are grassing people up to the police now.

We’ve turned into a nation of curtain twitchers happily passing judgement on others. Sad. However I’m more angry than anything else at the moment. Angry at our government who are happily spinning the lack of PPE while avoiding scrutiny as to why we are the worst performing country in Europe. Angry that daily stats are trotted out and we are almost numb to them now. Angry at years of underinvestment in the NHS. Angry that the Tories are riding this pandemic for all it’s worth.

But staying angry will get me nowhere. It’s not healthy and at the moment thats the only thing we can focus on. Staying healthy, following the rules and protecting the NHS so it’s there for our friends and family when we need it. Stay safe folks.

The Queens Speech

I’m no royalist but the Queens speech to the nation was damned impressive. Clear, honest and with a degree of hope. While she always speaks at Christmas this was only the fifth time in 68 years thats she’s addressed the nation on TV. Powerful.

Boris thanks the NHS

Another speech that was impressive was Boris Johnson on his release from hospital. It’s good to see he’s recovered from a nasty infection and I can only hope that his words, though well said, are followed by action. However he has form so time will tell if he really does value and protect the NHS.

So much living to do

Very few stories have been about the victims of Coronavirus. So much is made of stats, lockdown, Boris, that the huge number dying each day are often lost. So thank you to The Guardian who paid tribute to some of the people who have tragically lost their lives early.

Sick man of Europe

We are approaching (hopefully) peak infection in the UK but it’s disappointing that despite the warnings from Italy and Spain it looks like the UK will have some of the worst statistics at the end of this pandemic. Two views stand out. Germany and the UK started at around the same time and pace but the UK have came of far far worse – is this why? Also, this twitter thread from Elaine Doyle is really worth your attention. Why has Ireland been far less impacted than the UK? The UK were slow. I know also that there are big differences in population density but Ireland acted quickly and decisively like New Zealand. The UK took their time. The main question now – why aren’t the mainstream media questioning the government. There’s a fucking press conference EVERY DAY. Ask something other than PPE and what are the rules for ending the lockdown.

I’m Bored

If you are off work, missing going out at the weekends and can’t quite find something to do or watch then bored.solutions is for you. Basically it’s a site full of idea’s of what to do while self isolation with some handy filters to allow you to pick 1 day, weekly or 1 month challenges. Enjoy.

Here’s How Those Hot Jigsaw Puzzles Are Made

My mum loves jigsaws and thanks to the lockdown they are in hot demand and short supply. Loved this story from The New York Times that shows how modern jigsaws are made. I thought they would be far more automated by now.

Scotland after the trial of Alex Salmond

While the pandemic unraveled much of UK life, the trial of Alex Salmond concluded and in his favour. There’s much to unpack and so much of this story still to be told. This article from Dani Garavelli covers the trial and what’s still to come. There’s some uncomfortable days ahead when some more of what happened is finally revealed.

Avengers Endgame

Let’s end on a high. Endgame came out a year ago and these clips from the film alongside the opening night audience in New York are just joyous. Movie watching in America is very different to the UK.

Weekly Digest for Sunday 29th March

Flooded boat at Loach Ard

What a month. The impact of Coronavirus has now hit home in the UK…scrap that…across the whole world. What was impacting China and other Far East regions earlier in the year has now totally changed life in the UK and Europe. I can’t think of anyone right now who won’t have been impacted.

The “new normal” is what many are calling it. For me that means working from home. Trying to keep a routine, trying to do some sort of daily exercise, getting used to constant video and phone conferences. I’m lucky in that I can remain productive and keep doing my role remotely but others aren’t so fortunate.

Job losses, money fears, mental wellbeing and all that on top of the impact of the Coronavirus itself. People warned what a global pandemic could do to the world and guess what – they were right. Social media has become even more noisy and sometimes for good as well. Local groups forming, how can we help each other as we will all be impacted at some point. The negative is the constant shouting by so many people that the government is wrong. The scientists are wrong. They are too slow, they aren’t reacting, country x did this by now, why haven’t we, masks are vital….or they aren’t as it’s not airborne. CONSTANT SHOUTING.

Twitter feels like an anxiety amplifier at the moment. For every positive post there’s another 50 that are predicting doom. I’ve a particular hatred for those on social media that have pivoted from Brexit and/or technology and become scientists in literally two weeks. Impressive. Makes you question what they actually know as much of what they spew or retweet isn’t really fact but merely information that supports their argument. Try TikTok instead. Almost calming. And those that are still claiming it’s like a mild flu. That the lockdown is an over reaction. Fuck you. It’s not. It will kill lots of people in the UK well before their time. Friends and family. Hopefully not yours. Just today the first NHS frontline worker has died due to Coronavirus. This isn’t flu!

The difference when outside is stark. Empty roads and pavements and for the most part people are respecting the social distancing rules. Some don’t. Some get too close. Some look like they don’t care. Shopping is now queue’s with 2 metre gaps and empty shelfs. On a walk this morning three different police vehicles passed by, all the more obvious thanks to the empty roads. Police state? But then I’m judging those that can’t keep their distance – ticking off a shopper on Friday cause they couldn’t wait to grab the same goods I was buying. And I’m saying pavements are quiet but late morning to early evening they are really busy as people get some of their daily exercise. If the rates don’t start to plateau in a couple of weeks I can see the exercise guidance changing.

The impact of the virus will be felt for years. Economies tanked. Pensions bust. Economy is a funny one. All of a sudden we can find money for everything. Broadband is now a utility. Key workers are some of the lowest paid in our economy. The NHS is now getting the investment it should have had for the last decade. And Jeremy Corbyn has been proven right. The only thing proven is that it has and always was…all about him. Thanks goodness his reign is almost over. Also a small plea to tech podcasters right now…there isn’t much tech news at the moment, stop spinning out your podcast for advertisers. Thanks.

Didn’t expect to write all that but needed to vent. Before I finish with a few links just want to say one thing….stay safe.

The Doctor Who Helped Defeat Smallpox Explains What’s Coming

Coronavirus isn’t Smallpox but lessons from years of fighting it are worth understanding.

Coronavirus tracked

There are so many sites tracking the global spread of Coronavirus but I find the FT’s the clearest. No longer behind the paywall the datasets are fascinating. Great work from Steven BernardCale TilfordJohn Burn-Murdoch and Keith Fray.

As much as I like a graph this did make me chuckle

How the Pandemic Will End

Great long read on what’s happening now but more importantly what’s to come.

All The Streets

Davis Vilums cycled all the streets in London and also made a great site talking about it. Love this.

Google tracked his bike ride past a burglarized home. That made him a suspect.

This is scary. A man in America is accused of a crime as the tracking data from his app put him at the scene of a crime. With the increased powers at the UK governments disposal there needs to be checks and balances on the use of technology to fight the pandemic but also how it may impact on civil liberties.

Who Would Have Thought an iPad Cursor Could Be So Much Fun?

The new cursor support in iPadOS is great. And fun. Using it with the iMac’s trackpad and it works really well. The new Magic Keyboard, while expensive, is something I’m looking forward to trying later in the year. Really liked this series of tweets from Steven Sinofsky on the cursor update and the new iPad Pro’s.

30 years of hope: my life as an ardent Liverpool fan

This from March the 8th feels like a lifetime ago but it’s a great read and shows how important football is to so many people.

Deacon Blue’s City of Love

The new Deacon Blue album is one of their best. Great lyrics, strong melodies and a damn fine album up there with Raintown for me. This review is a love letter to Deacon Blue and like their new album I loved it. Give it a try – a bit of a tonic against the grimness of 2020.

Weekly Digest for Monday 2nd March

Looking over to Inveruglas from Inversnaid.

Feb was quite the stormy little month. Too much wind. Too much water. A whole lot of virus. For one reason or another I never got round to one of these posts until March. Oops.

How the BBC’s Netflix-killing plan was snuffed by myopic regulation

The BBC has been fighting Netflix, Sky, and now Apple and Disney with one of it’s hands tied behind it’s back. iPlayer was, and still is, an amazing resource but has often lagged Netflix and others. Now it’s probably too late to fight back, especially if the Tories (and crazy Corbynista’s) get their way.

The boss who put everyone on 70K

Dan Price shows there are other ways to run a company and make it a success. The unexpected side benefits are a real plus.

In Coronavirus Fight, China Gives Citizens a Color Code, With Red Flags

Only time will tell how successful each countries fight against the Corona virus is. China has used tech and it’s communist power in ways that very few others can emulate. It’s right that a government should use all power and tools at it’s disposal. Shame that China initially tried to hush it all up.

Google’s ambitious push into gaming is floundering, and it’s due largely to too few games on its Stadia platform — here’s why developers have held back

Few things unite gaming firms. However they are pretty united in condemning Stadia. The tech is great but the economics and the consumers sell just doesn’t make sense. This is dead.

Record breaking rainfall

No surprise that this last month has been the wettest February since records began in the UK. What really surprised me is the MET office graphic that had to go to 400% to cover off the rainfall totals. Wow. What you saying now climate deniers?

Tot

Mac text editors are ten a penny. Tot is a little different. It’s a small menubar based text scratchpad on the Mac that is free. It supports iCloud syncing and you can get it on iOS….where’s it’s £20. I’m loving it on the Mac but can’t quite bring myself to buy it on iOS yet. Well worth a download and try to see if it fits your workflow.

Behind the Scenes — Experiments IV: Fire & Ice

The Fire & Ice Apple add is lovely but far more interesting is the behind the scenes video on how it was shot. Clever.

PARASITE House Build

Parasite is a great film, and this video shows the Parasite house being built and walked through in The Sims. Watch the film, then watch this. Lovely.

The marketing genius of Lil Nas X

Wow – Things didn’t happen to Nas. Things happened because of Nas. Virality is not mystical. The story of Old Town Road is not magical. What a story!

Weekly Digest for Sunday 26th January

Dawn over a cold Loch Ard

Its a new year….a new decade…and somehow everything feels much the same. How does that work? It’s been a busy start to 2020. New bathroom has been fitted which was long overdue. It’s been 16 years since moving to Kelvindale and the home survey said we had a dilapidated bath. Well it did ok but it’s finally been replaced. Really pleased with the end result as it looks totally different to what we had before.

Also back in the swing of things at work. Three weeks off was lovely but bills need paying and as ever it only takes a couple of days before the break feels a long time ago. It also looks like being a big gadget year for me. New camera, consoles and phone. If the rumours are true the camera could be out in March rather than September. Need to get saving!

Does Microsoft Have a Boeing 737 Max Style Crash Every Week?

This really made me think. I’m increasingly more plugged in to the world of vulnerabilities, patches and enterprise security. This article posits that Microsoft and others are having huge Boeing type issues every week or two. Is that fair? When you see the speed that exploits are being taken advantage of it’s hard to disagree.

Blue Fucking Monday

Every January the news and hence Twitter, Facebook and advertisers tell us the third Monday in January is the most depressing. It’s bullshit but every year it’s dropped out like some wonder fact. Always remember…

Twitter for good

Twitter gets a pasting around negativity and being a cesspool and generally that is true. However there are gems on there. A bookshop was swamped with orders after they tweeted about a tumbleweed day at the store. Well done everyone!

Radiohead Public Library

Radiohead updated their site and turned it into a library. So much to see and hear – there’s a huge amount of material. Love it!

Game Stamps

I used to love collecting stamps when I was a kid. The Royal Mail has released a new set of stamps with screenshots from classic games. They look great and the screens were compiled with help from Bitmap Books, purveyor of amazingly good gaming books.

Instagram for Windows 95

Love the detail in this mockup for Instagram for Windows 95. Even the filters look spot on.

Viral Bowls

Bowls is a pretty traditional sport. They are getting players to wear shorts to jazz it up! However a shot from this weeks World Indoor Championships went viral due to the skill on display. My mum loves watching the bowls but I was so surprised to see the shot appear on Reddit with many people lost as to what the sport was. Who knew bowls could go viral.

Danny MacAskills Gymnasium

Love this guy. Another great video showing off some ridiculous skill and stunts.

Wardley Maps

A Wardley map is a map of the structure of a business or service, mapping the components needed to serve the customer or user. Wardley maps are named after Simon Wardley who claims to have created them in 2005. This form of mapping was first used in Fotango (a British Company) in 2005, within Canonical UK between 2008 and 2010 and components of mapping can be found in the Better For Less paper published in 2010.

Each component in a Wardley map is classified by the value it has to the customer or user and by the maturity of that component, ranging from custom-made to commodity. Components are drawn as nodes on a graph with value on the y-axis and commodity on the x-axis. A custom-made component with no direct value to the user would sit at the bottom-left of such a graph while a commodity component with high direct value to the user would sit at the top-right of such a graph. Components are connected on the graph with edges showing that they are linked.

Much of the theory of Wardley mapping is set out in a series of 19 blog posts and a dedicated wiki called Wardleypedia. As use of the technique has broadened to new institutions and been used to map new things the application of the technique in practice has drifted from the original vision.

Wardley Map Example

Links

Weekly Digest for Tuesday 31st December

It’s the last one of these for 2019 and the last of the decade. Woo. All the best for 2020 and the new decade ahead.

Media 2019

I’ve watched a lot of TV this year – the quality and quantity of TV thanks to the many streaming services that have launched is in some ways overwhelming. Highlights in no particular order: Line of Duty, Chernobyl, Watchmen, Fleabag, The virtues, The Mandalorian, Euphoria, The Expanse (binged seasons 1-3 in prep for seasons 4 – all good), Giri/Haji, Succession Derry Girls, Game of Thrones, This Way Up, The Boys.

As for films – Avengers:Endgame, Apollo 11, Booksmart, Fast Color, The Irishman, Marriage Story, Ad Astra. Gaming was strange this year – not much out as next year is new console time for both Sony and Microsoft so little to recommend apart from Apple Arcade.

Best Posters 2019

A good movie poster doesn’t always mean a good film. Here’s some of the best from 2019.

Recycling Sonos

This is bizarre. Sonos offer a 1/3 discount on your old product if you turn on “Recycle Mode”. But this bricks the device and makes it unusable. WTF!?! I’ve got a few Sonos devices but this will make me think twice about investing any more in their system.

Whats Next

Great article on the love for The West Wing right now. It’s one of my favourite TV shows ever and thanks to The West Wing Weekly podcast I’ve been rewatching all 7 series. There’s only 4 more episodes to go so it really will be a case of what’s next after January? If you’ve never watched The West Wing give it a try alongside the podcast…and if you’ve not watched it since it originally aired there’s no better time.

A Decade in Memes

Here’s a great list of memes that described the decade. Some classics in there.

Best of 2010s

I’ve linked to this a few weeks ago but if you are in need of more best of lists, Rex Sorgatz has pulled together an amazing index of best of decade lists.

Architecture Decision Record

An architectural decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

What is an architecture decision record?

An architecture decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

An architecture decision (AD) is a software design choice that addresses a significant requirement.

An architecture decision log (ADL) is the collection of all ADRs created and maintained for a particular project (or organization).

An architecturally-significant requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture.

All these are within the topic of architecture knowledge management (AKM).

The goal of this document is to provide a fast overview of ADRs, how to create them, and where to look for more information.

Abbreviations:

  • AD: architecture decision
  • ADL: architecture decision log
  • ADR: architecture decision record
  • AKM: architecture knowledge management
  • ASR: architecturally-significant requirement

How to start using ADRs

To start using ADRs, talk with your teammates about these areas.

Decision identification:

  • How urgent and how important is the AD?
  • Does it have to be made now, or can it wait until more is known?
  • Both personal and collective experience, as well as recognized design methods and practices, can assist with decision identification.
  • Ideally maintain a decision todo list that complements the product todo list.

Decision making:

  • A number of decision making techniques exists, both general ones and software architecture specific ones, for instance, dialogue mapping.
  • Group decision making is an active research topic.

Decision enactment and enforcement:

  • ADs are used in software design; hence they have to be communicated to, and accepted by, the stakeholders of the system that fund, develop, and operate it.
  • Architecturally evident coding styles and code reviews that focus on architectural concerns and decisions are two related practices.
  • ADs also have to be (re-)considered when modernizing a software system in software evolution.

Decision sharing (optional):

  • Many ADs recur across projects.
  • Hence, experiences with past decisions, both good and bad, can be valuable reusable assets when employing an explicit knowledge management strategy.
  • Group decision making is an active research topic.

Decision documentation:

  • Many templates and tools for decisison capturing exist.
  • See agile communities, e.g. M. Nygard’s ADRs.
  • See traditional software engineering and architecture design processes, e.g. table layouts suggested by IBM UMF and by Tyree and Akerman from CapitalOne.

Decision guidance:

  • The steps above are adopted from the Wikipedia entry on Architectural Decision
  • A number of decision making techniques exists, both general ones and software and software architecture specific ones, for instance, dialogue mapping.

How to start using ADRs with tools

You can start using ADRs with tools any way you want.

For example:

  • If you like using Google Drive and online editing, then you can create a Google Doc, or Google Sheet.
  • If you like use source code version control, such as git, then you can create a file for each ADR.
  • If you like using project planning tools, such as Atlassian Jira, then you can use the tool’s planning tracker.
  • If you like using wikis, such as MediaWiki, then you can create an ADR wiki.

How to start using ADRs with git

If you like using git version control, then here is how we like to start using ADRs with git for a typical software project with source code.

Create a directory for ADR files:

$ mkdir adr

For each ADR, create a text file, such as database.txt:

$ vi database.txt

Write anything you want in the ADR. See the templates in this repository for ideas.

Commit the ADR to your git repo.

ADR file name conventions

If you choose to create your ADRs using typical text files, then you may want to come up with your own ADR file name convention.

We prefer to use a file name convention that has a specific format.

Examples:

  • choose_database.md
  • format_timestamps.md
  • manage_passwords.md
  • handle_exceptions.md

Our file name convention:

  • The name has a present tense imperative verb phrase. This helps readability and matches our commit message format.
  • The name uses lowercase and underscores (same as this repo). This is a balance of readability and system usability.
  • The extension is markdown. This can be useful for easy formatting.

Suggestions for writing good ADRs

Characteristics of a good ADR:

  • Point in Time – Identify when the AD was made
  • Rationality – Explain the reason for making the particular AD
  • Immutable record – The decisions made in a previously published ADR should not be altered
  • Specificity – Each ADR should be about a single AD

Characteristics of a good context in an ADR:

  • Explain your organization’s situation and business priorities
  • Include rationale and considerations based on social and skills makeups of your teams

Characteristics of good Consequences in an ADR::

  • Right approach – “We need to start doing X instead of Y”
  • Wrong approach – Do not explain the AD in terms of “Pros” and “Cons” of having made the particular AD

A new ADR may take the place of a previous ADR:

  • When an AD is made that replaces or invalidates a previous ADR, a new ADR should be created

ADR example templates

ADR example templates that we have collected on the net:

For more information

Introduction:

Templates:

In-depth:

Tools:

Examples:

See also:

From https://github.com/joelparkerhenderson/architecture_decision_record