An Ode To Software Design Documentation

This is a departure from my usual discussions of politics, law, and current affairs - I want to delve into another area of interest for me - software engineering, and in particular what constitutes useful documentation. 

I know it's not fashionable among software developers to do "tedious" work like actually documenting design and architecture decisions.  Outside of domains where such documentation is absolutely mandated for regulatory reasons, the thinking tends to be "let's be Agile" and just talk about it as we go.  That's lovely for one-off projects where you might have a few thousand lines of code that is solving a singular and specific problem.  It absolutely sucks when you are creating infrastructure that you expect other developers to use. 

Here's the problem as I see it:  Infrastructure software in particular generally depends on the user having a working understanding of how it works in order to use it in any meaningful way.  A person coming into your infrastructure a decade after you made the first design decisions has no idea what those decisions look like, or the approach to partitioning the domain that you as a developer and architect took.  It is wholly inadequate to tell us "Oh, it's all in the API documentation" - although I can deduce certain things from the API, the public API still represents a wall to understanding the underlying architecture of the software and the assumptions it makes. 

My first exposure to this came back in the 1990s when a nameless software vendor decided to switch their implementation of the UNIX socket system from being based on BSD to being based on AT&T System V UNIX, and I had to migrate the product I was working on at the time from one to the other.  The result was catastrophic because what the vendor attempted to do was shove a "compatibility layer" in so that software using BSD socket conventions would still compile.  Sounds good right?  No - the result was catastrophically wrong. 

Here's where documentation came to "save the day" - although the process of getting there was about as much fun as removing porcupine quills from your backside.  It turns out that BSD sockets had different behaviours behind the scenes than System V sockets - in particular when handling certain kinds of faults. 

Sorting out the issues ended up taking a whole bunch of effort and eventually determining that for semantic reasons, you cannot successfully implement the BSD socket API on top of System V sockets (although the other way around can be done!).  If it wasn't for actual documentation of the specifications, it would have been next to impossible to make that determination.  

You might say "well, that's a very specific case, and it has been sorted out, so?".  

My response to that is this:  Even in the world of Open Source software, the same issues arise regularly.  Software is complex, and not everybody has the time - or inclination - to tear apart the code you have written to figure out the underlying architecture and design decisions.  Most people want to be able to _USE_ your software, but that really does mean making visible the fundamentals of the underlying design so that when we look at the public API you provide we can understand what we are interacting with. 

API-only documentation is absolutely useless if the intent behind that API is not made visible.  Likewise, good documentation has to be searchable, indexed, and approachable from different perspectives.  _YOU_ as a developer of a particular piece of functionality may be a domain expert both in the software and the problem domain, but not everybody who comes to your software will have the same background and depth of knowledge you do.  Your documentation should reflect a working understanding of that. 

Good design documentation - even if it is written "after the fact" is still valuable because a decade after you wrote the software, someone else may encounter it and have to pick up where you left off.  In my professional career, I have had to jump into code that someone else wrote many times.  The people who bothered to document their designs made my life much easier in the long run (and usually wrote far better solutions).  

Yeah - I get it - not everybody wants to sit down and write out plans for what they are going to build - it's way more gratifying to get into coding and make things work.  You know what?  Good design that you can actually document is almost always going to provide you with a better solution in the long run - and future you may even benefit from it.  

Governments Seizing Powers They Have No Right To

In Alberta recently the UCP government has written a number of laws which undermine the role of the courts as a check on power.  There are several strategies that are being deployed, and all of them ultimately attempt to make it impossible for citizens who are affected by these laws to access any kind of remediation for the harms done by the law. 

There are several strategies in play that we need to talk about.  Some of them I have already talked about in considerable depth here, the others I have not addressed yet, and this post will serve as a jumping off point for thinking about these things.   

The strategies that are being used are: 

1. The Notwithstanding Clause
2. Final Decision Rests With The Minister
3. Self-Indemnification Clauses 

May I Introduce The Phrase "Ultra Vires"?

Alberta plans to invoke its "Sovereign Alberta" legislation as part of "fighting back" against federal firearms legislation that bans firearms that are commonly seen as "military-style".  As the first application of the "Sovereign Alberta in a United Canada" legislation, you can expect to hear a lot about this subject in the coming months.  

I'm not going to opine on the merits of the federal legislation/regulations at issue here.  Gun control and rights around firearms in general are contentious at the best of times, and I think that people who are on either side of the issue already have their opinions and arguments set out.  

This post is going to be about the "Sovereign Alberta" legislation and what it purports to do.

The UCP Is Not A Reasonable Party

 So, Danielle Smith was booed at the UCP annual convention last night.  Why?  Because she signed a deal with Ottawa.  Nobody should be surprised by this - least of all Danielle Smith.  

I'm not going to analyze the "MOU" that was signed in this post - that's a topic for another post when I have some time to digest the implications of that deal.  This is about the UCP and the fundamental nature of the party.  

Formation of the UCP

The UCP is not a "reasonable party", and it was never intended to be. The UCP arose not from the PCs, but from most radicalized wings of the Wildrose Party - the ones who remained after the disastrous floor crossing that Smith and Prentice engineered in 2015.  That was always the foundation group.  Then Kenney spent much of 2016-17 cobbling together an "alliance" of PCs upset that they lost the 2015 election, and a collection of increasingly radicalized groups including known neo-nazi groups, separatists, and the usual assortment of religious extremist groups and so on.  

Now, while I don't count Kenney among the separatist and neo-nazi types, his own background is hardly one of moderation.  He learned to stow his worst instincts in the mill of Ottawa politics, where moderation is an absolute because you won't get very far if you piss off various major factions.  Kenney himself comes straight out of the Prairie Reform movement, and his entry into politics had a lot to do with a stint as an anti-abortion activist in a US college.  He is rumoured to be connected to the hardline Catholic group Opus Dei.  His opposition to gay marriage was vocal and persistent, even after the fight was long lost. 

Naively, Kenney believed that he could do the same thing his buddy Harper had done federally - hold them together with a combination of identity politics and an iron fist.   That fell apart when the COVID pandemic hit, and suddenly the necessities of governing required Kenney to act pragmatically, rather than ideologically.  

Instead of acting decisively on the pandemic, Kenney waffled about attempting to both assuage the fears of everyday Albertans who were looking at what was happening in China, Italy, and other countries with horror, and simultaneously trying to keep a base of party members who had swallowed the paranoid conspiracy theories around COVID.  

Make no mistake, Kenney gave oxygen to conspiracy theorists and other radicalized types by providing direct support to the "Yellow Vest Convoy" (remember that?), and then tacit (and back channel) support to the "protestors" who occupied the Coutts border crossing as part of the larger "Convoy Protest" in Ottawa.

Kenney's Downfall

What Kenney no doubt tried to frame as "pragmatic governance" didn't mollify the radicalized types in his party like David Parker, who set about engineering Kenney's ouster in late 2022, paving the way for Danielle Smith to take over with the backing of Take Back Alberta and others. 

As he was exiting his role as party leader, Kenney darkly quipped about "the lunatics are taking over".  He was correct, but in doing so was ignoring his own role in their power in the party.  Whether he admits it or not, he gave the extremists a political home, and then fed them. 

Remember his threats about "Alberta Separatism" in 2019?  2019 Jason Kenney saw these people as tools he could control and manipulate the way that Harper did.  He misunderstood the dangers that giving extremists a voice carries in politics.  Extremists - and yes, I include Manning-era Reform backers in this group - don't want to listen, and they resent any effort to reason with them.  They're convinced they know the answers already.  

Kenney the political organizer met his match in David Parker - also a political organizer.  Kenney's miscalculation cost him his opportunity to step back into Federal politics with a reputation in CPC circles as an organizer who knows what he's doing, and with "cred" having been a "successful premier".  Kenney didn't fight back publicly against Parker's paranoid conspiracy theory laden activism.  Instead he tried to play things through the back channels of the party - a party which he constructed, but also that had the very internal weaknesses that had plagued Kenney's efforts in Ottawa.  

He acquired the nickname "Bumbles" in conservative Ottawa circles for the inevitable fumbles and overplays that seemed to follow him.  That same blindness to optics, and a belief that he could lie his way out of anything, ultimately came at a very high price for Kenney as Parker organized a backroom ouster right under Kenney's nose by leveraging paranoid conspiracy theories left and right. 

Kenney's UCP was fundamentally a vehicle for Kenney to ride back into federal politics, and hopefully the Prime Minister's offices.  From that perspective, the UCP was little more than a cynical creation of a man driven not by ideology, but by power.  Kenney was an opportunist, but he was also bounded by his experiences in Ottawa.  He wasn't a good premier per se, but he wasn't the authoritarian we see in Smith.

The Rise of Smith's UCP

In the wake of Kenney's ouster at the 2022 AGM, who should emerge as a replacement for Kenney but none other than Danielle Smith.  Smith's political history is one of making a bigger mess every time she surfaces.  Her first foray into elected politics was as a Trustee for the Calgary Board of Education (CBE).  That was cut short when the province stepped in and dissolved the board because of the levels of dysfunction and conflict that Smith herself played a central role in creating. 

Smith would disappear from elected politics for a while, surviving as a columnist for the Calgary Herald - writing such illuminating works as arguing that there might actually be benefits to smoking, among other gems of wisdom.  She would return to elected politics by becoming the leader of the Wildrose Party in 2010 - only to snatch defeat from the jaws of victory in the 2012 election.  This was followed by a disastrous floor crossing exercise in 2014, which torpedoed her support. 

Again, Smith left elected politics, this time becoming a lobbyist for the energy industry, and sometime talk radio host.  

I'm sure you see the pattern by now - every time Smith gets involved in elected politics, she makes decisions which are horribly detrimental to those around her.  In this respect, "Smith's UCP" really isn't her party.  It's the party of malcontents like David Parker and TBA, with Smith as the "useful idiot" figurehead.   

Smith's UCP (or perhaps more accurately TBA's UCP) is clearly authoritarian - and not in a good way.  Smith and her government are ignoring Albertan's voices and concerns, plowing ahead with an agenda which they actively avoided campaigning on during the 2023 election cycle.  

More pointedly, the government has taken the approach that their first legislative priority is based on whatever the party slid into the "party platform" during the last AGM.  This was made abundantly clear in 2024 when Smith announced a series of legislation attacking the transgender community.  That was definitely not a matter on the election agenda, and outside of the queer community, I'm pretty sure that most people were stunned by it.  

Then, let's look at their approach to "negotiating" with teachers.  Instead of negotiating, the UCP legislated them back to work (a perfectly common approach).  However, the legislation was very telling.  Instead of committing to binding arbitration, the government simply legislated a contract that had been overwhelmingly rejected twice by teachers, and then slammed the door on any kind of "labour action" by invoking the Notwithstanding Clause (S33) in The Charter of Rights and Freedoms.  

Meanwhile, they are actively tearing apart the healthcare system, without the consent of Alberta voters.  This dismantling is again, largely driven by the manufactured outrage of TBA and its leadership in the wake of the COVID pandemic.  Policy driven by anger, or other emotions, is seldom "good policy", similarly, policy which is not carefully moderated by pragmatic consideration is also going to be bad policy.  It's not new in Alberta that there has been a faction that wants to align the province with US policy on many fronts (usually with the greatest amount of cruelty possible).  

Past governments have carefully avoided following those pressures, knowing full well that such things are contrary to the broader values of Albertans.  Not the UCP.  The UCP forges ahead in the most violent way possible - taking a wrecking ball to the infrastructure of civil society, and using moral panics like their attacks on transgender people as a distraction.  

This is not a party that actually supports individual freedom, it is now a party that supports "freedom for me, not for thee" - if they don't "approve" of your particular brand of freedom (e.g. being transgender), well - expect them to legislate it away from you and then tell you that it's their right do so.  

Smith herself may or may not be an "authoritarian", or she may simply be their "useful idiot" who is willingly standing in front of the public and doing as she is told.  It doesn't really matter - either way, she has cast her lot with people who ARE authoritarians, and have decided that instead of having a discussion with Albertans, they are going to seize power and impose their will on the rest of us. 

There is no reasoning with the UCP in its current form.  The best we can hope for is that they continue to break into factions fighting over control of the party.  Hopefully those factional squabbles will eventually tear the party apart, as it should have done once the project Kenney set the party up for collapsed on itself. 

Bill 9 and Smith's Justification For Invoking S33

 Over at the Government of Alberta website, we have the government's propaganda piece trying to justify using S33 to stomp all over the rights of transgender Albertans, their parents, and women in Alberta sport.

I will put screen captures of the whole page at the bottom ... just in case the UCP decides to disappear this link.  

As you might expect, it's largely a load of bollocks with a side order of moral panic thrown in.  Let's talk about that for a moment, because Albertans deserve far better from our government than this. 

An Open Letter To Premier Smith

Dear Premier Smith, 

It wasn't that long ago that you were standing at the podium telling us that Bills 26, 27, and 29 were so well crafted that you were certain that they would prevail in scrutiny before the courts.  Today, you stood up and told Albertans that these laws were so vital and important that you were going to invoke The Notwithstanding Clause (S33) to bring them into force.  

What changed? 

It wasn't the content of your hateful legislation - I read Bill 9 - it didn't do anything except add in the invocation of S33 to each of them.  So, your legislation didn't change, nor did the intent behind that legislation.  I don't think we need to kid ourselves about the intent either.  

Was it your rabid base of TBAers getting restive because the court cases were taking longer than their pathetic attention spans?  Or did you need another distraction from the blatant corruption and mismanagement that your government has been foisting on Alberta since you became Premier?

Frankly, I don't really care.  You just abused S33 again - proving that your oh-so-heartfelt concerns about "parliamentary sovereignty" are little more than a power grab - one where you put yourself in the position of arbiter of who gets rights in this province, who gets their freedoms stripped from them, and who is considered a valid citizen of not only Alberta, but in fact Canada.  

Fuck you, Danielle.  Do the province two favours:  retract Bill 9, and resign.  Alberta deserves so much better than a wannabe dictator who sees Canada's Constitution and The Charter of Rights and Freedoms as an obstacle to be ignored.  

- A Citizen of Canada

The Charter Is Far More Complex Than This

So, over at Macleans, we have an opinion writer who thinks the Notwithstanding Clause (S33) is a "Good Thing". 

The author largely is making the argument that "too much power is concentrating in the courts", and that a tool to mitigate that is necessary, lest we have judges "legislating from the bench".  Predictably, the author eventually arrives at the language of "judicial overreach".  

Here is the problem with that kind of reasoning on the author's part:  What they consider to be "judicial overreach" is basically matters where it doesn't affect their rights directly.  Whether or not the author likes a court ruling, or a particular piece of legislation that limits rights if they are not directly affected by it.

I doubt very much that the author is directly affected by Saskatchewan's "pronoun law", nor Alberta's laws attacking transgender people (which the UCP government is expected to table legislation invoking S33 on imminently).  

The problem isn't "judicial overreach" here, it's conservative governments which have taken an overtly authoritarian stance regarding rights guaranteed under The Charter.  Smith is basically saying "people I like get their rights recognized, but because I don't like transgender people, their rights can be curtailed, or even outright erased.

Were conservative governments using S33 in rare, but reasonable ways, the author might have a point.  They aren't - they are using them to push forward legislative hobby-horse agendas that have been imported from abroad and to extinguish rights and public participation by those affected.  

Is there a reasonable case for using S33?  Yes, there are - but they are exceptionally rare, and deservedly so.  If The Charter makes writing legislation more difficult for legislators, then the application of S33 should be orders of magnitude more difficult specifically because it can be used to extinguish rights. 

The author complains about one or two rulings, but only in the most pithy of ways, making it clear that they have neither read the rulings, nor bothered to take the time to understand how precedent law influences the courts in interpreting The Charter.  

Further, unlike the US Constitution and its Bill of Rights, the Canadian Charter of Rights and Freedoms contains language which is interestingly written to be inclusive - not merely in the moment of writing, but in fact is intended to be very much a living document.  The authors of The Charter weren't so arrogant as to believe that they knew all the topic areas which it might be called upon to address in the future, so they included carefully written language that makes it absolutely clear that things can, and will, be "read in" in the future. 

Allow me to bring to your attention the wording of S15(1) of The Charter: 

15 (1) Every individual is equal before and under the law and has the right to the equal protection and equal benefit of the law without discrimination and, in particular, without discrimination based on race, national or ethnic origin, colour, religion, sex, age or mental or physical disability.

The phrase highlighted above reads "and, in particular ...".  This is probably one of the most important phrases in the entire document because what follows are a list of prohibited grounds of discrimination.  However, that phrase makes it abundantly clear that the writers of the document fully anticipated that other grounds of discrimination would be identified, and would need to be encompassed by this clause.  

What it is not, is an exclusive phrase - the list which follows is not intended to be the sole list of prohibited grounds.  

Does this make writing legislation more difficult?  For legislators like Alberta's Premier Danielle Smith, it most certainly does because much of the legislation her "base" in the UCP are demanding is clearly intended to attack rights for purely political reasons.  Whether this is the rights of transgender people, or the rights of teachers is irrelevant to me.  Curtailing rights guaranteed under The Charter should be hard.  Giving legislators too lazy to do the hard work of writing good legislation a sledgehammer is a horrible idea. 

The author would do well to remember that just as Danielle Smith likes to argue, that the legislature has supremacy (it does - it is the only body empowered with writing laws), the Constitution of Canada and The Charter itself are also the result of legislative supremacy.  So, before we allow legislators to arbitrarily curtail rights, we should absolutely insist that doing so be the hardest task a legislator faces.