We are nearing a plateau. I believe that the next order-of-magnitude gain in accessibility won’t come from ever-tighter contrast ratios or perfection in semantic HTML.

We’ve reached the point of diminishing returns. We might build current best practice levels of accessibility faster and more effectively with better technology. Still, we are bound in our current approach to accessibility by the interfaces we ship. The next leap in accessibility cannot come from better execution of traditional interfaces; it can only come from changing the interface. Changing the interfaces means making them adaptive. Making them personal and responsive in ways that statically designed software can never achieve.

That change will come from agents. Agents are the next step in digital accessibility.

By agents, I mean allies that help you and increasingly act on your behalf. These agents will translate, reshape and personalise every interface an individual might need. In some cases, that agent will be your personal agent; in others, it will be an agent provided for you to use by the company you’re interacting with. Either way, these agents will be accountable for ensuring that the things you need to interact with, screens, video, forms and more, will be exquisitely tailored for your unique needs.

At one end of the spectrum, that might mean synthesising the information you’re reading with relevant insights from elsewhere on the internet.

On the other hand, it might mean actively interpreting for you, turning information that was previously inaccessible into something you can use instantly.

Imagine a world where anyone with macular degeneration can fill in their Lotus Notes timesheets!

Or where your personal agent spends a day learning your unique colour perception profile, then shares it with Netflix’s agent, which re-colours every show you watch to give you the most vivid picture possible.

If agents can reshape interfaces in real time, they don’t just make things easier; they change the rules of interface development. The most significant rule they will break is the tradeoff between usability and accessibility.

Dissolving the accessibility-usability dilemma

For years, we have wrestled with a false choice: make a product fully accessible and risk adding friction, or make it frictionless and knowingly exclude users. Agents dissolve that tradeoff. They will adapt to interfaces and needs in real time.

With the right tech and design, agents can deliver rigorous accessibility AND effortless usability simultaneously. The same agent that makes Lotus Notes usable for a user with macular degeneration can also streamline the workflow for a power user by skipping the UI and hitting APIs directly - without forcing either of those users to compromise.

To make agents truly helpful, we need to give them the same usage cues we give humans today, but in a form that agents can read and act on. In design, we call these cues ‘affordances’.

What are affordances?

Affordances are the characteristics or properties of an object that suggest how we can use it. They show a user that an object can be interacted with.

As such, an affordance is not a “property” of an object (like a physical object or a User Interface). Instead, an affordance is defined in the relation between the user and the object: A door affords opening if you can reach the handle. For a toddler, the door does not afford opening if she cannot reach the handle.

An affordance is, in essence, an action possibility in the relation between user and an object.

When your software’s user is an agent, the affordances you build must be designed for machine interpretation and action, not just human user perception.

Let’s look at three areas where agent-friendly affordances unlock capabilities beyond human limits, starting with precision.

Beyond-Human precision

Today, surgeons use machines in surgery where human hands lack the precision needed to achieve the work safely. Tomorrow, a world awaits us where NOT using a machine will be considered malpractice.

Imagine that conversation between two surgeons, “What!? What do you mean you didn’t use the robot to suture that vein back together! You just aren’t that accurate! No human can be after three hours of surgery!”.

What would the world need to look like for this to be possible?

We would need to have built the affordances necessary for an agent to interact with external tools and the patient. We would need safety and security guarantees, and we would need signs of confidence and doubt so that humans can review and intervene as needed.

In short, we would need equal affordances for the robot and for the human. We might need:

• Some kind of semantic data mapping of the human body that an agent could understand and apply knowledge to (Agent: “the patient’s blood pressure is stable, if it drops, I need to check for bleeding and respond with the appropriate tool immediately”)
• Tools that provide telemetry and other feedback via APIs (Agent: “Anaesthetic is being consumed at the expected rate given patient physiology, if rates change up or down, I will pause and escalate for human review”)
• A state machine for agents (Agent: “The state of the cardiopulmonary bypass machine is 12, subcomponents are in state 3, 7, 16 - I have mapped out a response plan if these states change.”)
• Insight into control states for humans (Human in the loop: I can see that the robot is in a planning state for the following surgical task and is anticipating three scenarios. I can see the plans for those scenarios and have pre-approved those actions only)

These examples show that the affordances we need for agents are the same as those for a novice surgeon. We need clear insight into the “headspace” of the novice, we need the novice to understand the capabilities of the tools they have at hand as well as how they can use those tools to achieve their plan (i.e. the theory knowledge and the applied knowledge), and we need someone with experience who can provide feedback in the moment that improves the performance of the novice. None of these affordances are new; we’re just applying them to computers that we use to apply only to humans.

If precision is about moment-to-moment execution, diligence is about never missing a detail, no matter how long you look or how deeply you dig.

Beyond-Human diligence

My team is currently building payroll software. It may be the first agentic payroll software in Oceania, if not the world. We’re planning and actively investing in a world where we can ensure that you are paid correctly by inspecting every single pay packet you have ever received, every time we calculate your next pay packet. A world where we can review 10 years of your tax history, 10 years of superannuation contributions, and 10 years of deductions and bonuses. Every single number that has ever been associated with you and your pay, for 10 years or more.

Payroll is a highly complex, compliance-heavy domain. Mistakes trigger legal penalties that can run into the millions. In Australia, if a company pays an employee incorrectly, the individual payroll staff member involved in that transaction can be jailed!

The pressure to get it right is massive, and the longer your employee is with you, the more data you have to check and re-check every time you pay them. Many of my customers have been with us for over a decade!

Can you imagine a human reviewing that for ten, a hundred, a thousand, or ten thousand employees? Picture this: It’s the end of the financial year. If you are in agriculture, this is your equivalent of moving day. If you’re in retail, it’s Black Friday, and it’s flu season in healthcare.

You’re the CFO. Your payroll manager walks into the room and says, “We’ve reviewed 100% of the payroll transactions we’ve made for about five thousand staff employed in the last seven years against every change in tax and holiday law in that period. We found three issues and fixed them. You can sign off on the end-of-year accounts.”

Previously, the payroll manager would have sampled the data with the risk of issues slipping through the cracks. In most cases today, your end-of-year accounts process is focused on the yearly period in question, and the amount of reports and data needed is enormous. Most companies (at least in New Zealand) can’t afford to hit the depth level they would like, which is why we have auditors routinely come through and do things like Holidays Act reviews and remediation.

The affordances we need for this level of automated compliance audit look very different to the affordances required for surgery.

We need:

• Immutable event logs (time-ordered records that afford the agent insight into the history of the employee they are checking)
• Semantic tagging of transactions (to convey intent and interactions around pay configuration)
• Rules versioning (to ensure the agent understands how to reconcile changes in the legislative environment against changes in configuration)
• Scalable Audit APIs (to simplify data access for the agent and provide interactions with other services)

With this level of diligence, when the auditors come knocking, the CFO is ready and can confidently prove every decision and every cent spent.

Now imagine what happens when this diligence is applied globally across industries. That’s how supercycles unlock new markets.

Beyond-Human eyesight

Agents can breathe new life into software you can’t use just as well as it can solve for software you hate using - without having to rewrite it from scratch.

Macular Degeneration New Zealand estimates that 10% of the 45-85 age bracket suffers from macular degeneration. That’s ~3-4% of the total population of New Zealand. What would it be worth to your company if you could increase the available market for your product by ~3-4%? If you’re selling a B2B SaaS product and you’re stuck with a system whose accessibility is poor, a 4% increase is massive.

Previously, unlocking that new market would be expensive! You either retrofit accessibility into a system that was never designed for it, using technology that was never built for it (anyone remember Adobe Flash? Good luck making that screen-reader compatible), or you rewrite significant portions or the entirety of that product!

With your own personal agent the story is very different. IBM is never going to update your particular version of lotus notes, and yet every fortnight, with an eye condition like macular degeneration, you’ve got to fill in your time sheet. You’re a skilled analyst, but this clunky, inaccessible user interface turns a ten-minute job into half an hour or more of struggle, every week, every fortnight, until you die or leave the company.

Not only can agents dissolve the accessibility-usability dilemma, they can give you a usable facade over unusable software. Your agent can consume the underlying APIs that Lotus Notes uses, unlocking a natural language interface to your timesheets. Whether it’s text or voice, you ask your agent to fill in your timesheet, you’ve worked on these three initiatives this week, and the time split is around 20%/40%/40%, and the agent converts that into the API calls needed to fill in your timesheet. If I were making ANY timesheet software today (#startup-idea), I’d bin my UI and create MS Teams, Slack and Discord bots that convert your text or voice into valid timesheets. Not Hipchat or Flowdock though. No nice things for those people.

Flowdock aside, we have a moral imperative to make these systems accessible; it is the right thing to do.

This principle works for any legacy software that can make rapid accessibility gains, to say nothing of software built with accessibility at its core. Eyesight is just one example. Every tech supercycle has expanded access or created new markets, and with agents, we’re about to see it happen again.

Accessibility remains a moral and commercial imperative

Consider this: I’m a company that today sells inaccessible software as a service. I charge $20 monthly, and New Zealand has about 5 million people. Adding 4% of that population to my serviceable addressable market, I can now sell to 200,000 new customers. If I win 5% of those, I can add 10,000 new subscribers and increase my annual recurring revenues by $2.4m. The total addressable market of New Zealand - that five million - is small fry. In June 2024, Sydney had about 5.5 million residents. Accessibility is money. Pure and simple.

These supercycles - PC, e-commerce, Cloud Computing, Mobile Web, and now AI each unlocked new markets with brand new users and unlocked new interactions that expanded existing markets. They made previously inaccessible systems accessible for those who were previously excluded.

The PC created markets, and e-commerce turned local and regional markets global. Cloud computing unlocked new markets by drastically reducing the barrier to entry for brand-new types of companies. AWS had a five- to seven-year head start with startups that used cloud computing to reach new markets faster than the incumbents could keep up. Mobile Web put a device in the pockets of billions of people who previously might have struggled to buy expensive computer hardware!

Enterprises responded to these market changes by either building new products native to the ideas of that supercycle or retrofitting legacy systems with the tech needed to play in that new market, even if the outcomes weren’t as technically pure as building from scratch.

How to build affordances for agents

Affordances in UI/UX include clear and consistent navigation patterns, breadcrumbs, and semantic markup that conveys intent and relationships. In back-end services, affordances include machine-readable APIs with consistent patterns and discoverable endpoints, semantic metadata, explicit error signalling and recovery protocols, data provenance, and separation of commands from queries. All of these things help humans use and build systems today!

All of them are necessary for agents to use and build those same systems tomorrow.

Consider building a significant integration into a product or system never designed for it. If you treat affordances for agents today, you will feel the same pain tomorrow as you felt building that integration. Maybe more so.

We already strive to build clean interfaces with clear documentation and unambiguous behaviours. We do this for humans and third-party developers who want to integrate with us.

The only difference is that tomorrow’s third parties will be agents. Those agents will expect the same affordances we build today, and the customers those agents serve will expect that your software works with their agent (or your own).

So, what can you do today to best prepare? If you don’t happen to be rewriting your whole product from scratch, what can you do to ensure that your product meets the prerequisites for agentic success?

Concrete steps teams can take today

Audit current affordances to identify gaps in context or access.

In surgery, an agent can only act safely if it knows what tools are available, what states the patient is in, and what the patient’s vitals mean. If those affordances are missing, the agent is blind.

• Start by mapping the interaction surfaces of your products. Any place a human or machine can read, write or otherwise interact. Ask: If the user were an agent, would they have all of the information they need to understand what is possible here?
• Look for missing cues; this might mean e.g. unclear navigation, inconsistent APIs or documentation or poorly or uncommunicated state changes.
• Treat this like a penetration test, but for usability. You’re trying to find where an agent would be blind or blocked because of missing affordances.

Add semantic metadata, ensuring every entity/event is machine-readable.

Agents cannot guess intent. They cannot be aware of the conversations that were had in the room back during design time. They only have access to what you grant them at run time. Provide explicit signals for use that convey intent. Add semantic tags to your data models, events, and UI elements to make their meaning unambiguous.

For example, you might return a response to a UI that looks something like this:

{
  "content": {...}, // omitted for brevity
  "metadata": {
    "workflow_stage": 3
  }
}

In payroll, an agent can’t guess that "workflow_stage": 3 means “awaiting approval from a payroll manager”. Your UI might store an enum that maps 3 to something a human might understand, but your agent won’t know what to make of this. You might resolve this in a few different ways. One option might be to ship a representation of the enum class with every response, but I can hear the purists in the back groaning about extra bytes over the wire, so what if we just did this instead:

{
  "content": {...}, // omitted for brevity
  "metadata": {
    "workflow_stage": 3,
    "workflow_description": "Awaiting approval from a payroll manager"
  }
}

This simple change tells us (and our agents) a lot! This is a payroll application, and we expect a manager to approve this task. An agent can then curry that information into whatever other process is needed. A small change can make a big difference.

Separate commands and queries to clarify state changes vs information retrieval.

In a legacy retrofit, an agent filling in a Lotus Notes timesheet should be able to read current entries without risk of accidentally writing changes. In surgery, separating “monitor vitals” from “adjust anaesthetic” presents a clear safety improvement.

Splitting reads from writes benefits modularity and encapsulation, scalability, and keeping interfaces small and clean. It can also substantially de-risk agent use of your software!

Separating reads from writes creates structurally clear and governable ways for agents to interact. Want a read-only agent? Scope its token to your read surface. Want your agent to plan before acting? Give it the context that API 1 is for planning and API 2 is for executing.

CQRS makes it easier for agents to plan, simulate, and validate actions before committing. We want agents to be cautious and measured, like human operators.

Expose intent surfaces, letting agents understand why actions are taken.

Agents are like my 10-year-old. He craves the “why” of things. Agents need that “why” as well, not just the “what”.

In our JSON example above, you saw that we exposed a metadata block in our API response. That metadata block is a crucial intent surface. Intent surfaces are metadata or API endpoints that explain the rationale behind specific actions we might take, are taking, or have taken in the past.

Consider this API response for a payroll adjustment

{
  "content": {...}, // omitted for brevity
  "metadata": {
    "reason_code": "overtime",
    "policy_reference": "HR-OT-2024"
  }
}

With a response like this, an agent understands that we’ve adjusted pay because a staff member has worked overtime, and to ensure compliance, the agent can cross-reference (via RAG or e.g. an HTTP request to a document store) the overtime payment against the policy. It can do this as a matter of course for all overtime payments or only for anomalous overtime payments (because they are high, or low, or on an unexpected or unusual day of the week or for any other reason). The agent can do this check at audit time, or it can do it asynchronously while the pay run is still being worked on - so we can look back in history and spot issues AND prevent new problems from appearing.

Implement provenance hooks to track data origin and transformations.

Provenance is the audit trail for meaning. Every piece of data should carry its origin, transformation history, and trust level.

When data carries this information, agents can verify accuracy, detect anomalies and explain decisions to humans.

A medical agent deciding on a treatment plan (perhaps after the surgery we discussed earlier is complete) can trace lab results back to a specific machine, calibration date, and technician and flag if some aspect of that calibration might have a material impact on the patient’s well-being.

These steps aren’t solely about future-proofing in the abstract; they’re about making your systems agent-ready now. The teams that start today will be the teams whose products feel inevitable across the next supercycle. Everyone else will be scrambling to retrofit under pressure.

Conclusion

Take yourself back to the year 2000 once more. The iPhone is coming. Android is nearly here. What would you do if you were there again? I believe that we are there today. You might argue about the moral rights and wrongs of AI, or you might think that we are in a massive bubble. You might be right. But the e-commerce supercycle lasted a full decade after the dotcom bubble burst. The bubble was a harbinger of a changing world.

We are at the start of a new supercycle. A supercycle of agents, that I believe will be bigger than cloud computing, bigger than the mobile web, bigger than e-commerce. Maybe even bigger than the PC.

The Helpful Web: humans and AI allies expanding access for everyone. Accessibility isn’t just inclusion — it’s growth. Audit your affordances, design for agents, make AI your company strategy. In ten years, bypassing your agents will feel like malpractice.

References

[1] What are Affordances? , IxDF

[2] About Macular Degeneration , Macular Degeneration New Zealand

The way we design them - and the way we design the organisations that build them - determines whether they flourish or wither.

Over the years, I’ve come to see architecture not as a static blueprint or a master plan, but as an act of cultivation.

This article is the first in a series exploring my personal philosophy of architecture: how we can guide complex systems, human and technical, with the same care and intention as a gardener tending a landscape.

Here, I’ll start with the metaphor itself - why I believe architects are gardeners - before moving on in future pieces to define what architecture really is, how to build sustainable practices, and the principles and tactics that make them work.

The way we structure our communications with one another is the single biggest determinant of what our architecture will look like when it’s done.

You design a system that looks different to the way you structure your communications. Over time, without great effort, that design will slowly be subsumed into one that more organically maps the teams and business units that made it.

We have two choices open to us then:

• Plan, account for it and attempt to design around it
• Let it happen

It’s not clear to me that either of these approaches are inherently wrong.

Expanding, our choice is whether we fight the change those communication pathways bring or whether we guide that same flow, co-opting its’ force and nudging it left or right towards where we wish it. This philosophical question is not unlike a question many gardeners have faced over the years. Gardening is an excellent metaphor for the activity of architecture.

Architects are gardeners that cultivate renewable systems (both human and computer)

It is powerful and freeing to consider that we are all gardeners of systems that will outlast us. Years before publishing his book, The Software Architect Elevator , Gregor Hohpe describes large socio-technical systems as gardens :

Large-scale IT is much like a garden: things evolve and grow on their own. Weeds tend to grow the fastest. The role of the gardener is to trim and prune what does not fit and to establish an overall balance and harmony in the garden, keeping in mind plants’ needs, for example by planting shade-loving plants near large trees or bushes. A good gardener is no dictatorial master planner and certainly does not make all the detailed decisions about which direction a strain of grass should grow – Japanese gardens being a possible exception. Rather, the gardener sees him or herself as the care taker of a living ecosystem.

The gardener is an actor within that system who tends to its’ health. Pruning, planting and maintaining from within the system itself.

This philosophy contrasts sharply with the French notion of gardeners as kings and gods outside of the garden they curate. We’ll explore the French approach and compare it to a traditional Japanese Zen garden where the mindset of that Zen gardener is closer to the culture and approach architects should employ.

By acting as gardeners rather than emperor-kings, architects can guide large projects and embrace the flow of the project rather than fighting the chaos inherent in the group hallucination these projects inevitably are.

The Garden at Diago-ji, Kyoto

Consider the garden at Diago-ji in Kyoto, pictured below. What do you notice about it?

How is it assembled? What structural elements can you identify and how do they come together to form the garden?

Do you find the garden aesthetically pleasing? Do you find it calming or exciting?

What level of effort do you imagine it took to plan the garden? To plant and to grow, and to maintain it?

Fix those answers in your mind and then consider the garden constructed at The Palace of Versailles.

Consider the same questions about the effort taken to plan, plant, grow and maintain.

Consider the aesthetics. Consider the “mouth-feel” of both gardens. Where do they do the same things? Where are they different?

This is an entirely different construct to the garden at Diago-ji yet they are both gardens, maintained by gardeners. Both have plants and engineered constructions. Both are beautiful and satisfying to view, and yet outside, they are almost entirely different!

Why? What can we learn about the gardeners through viewing and considering each choice made in these gardens?

Sailee Khurjekar at philosophynow.org can help us here.

They describe that

Garden design in the Japanese tradition presents an alternative approach to the English tradition. The properties of the natural objects are not altered to suit an aesthetic design, as an ‘English garden’ designer might cut down a shrub so that it is neat and symmetrical, with the sole aim of pleasing the observer. Instead, in a Japanese garden the organic properties are manipulated to enhance the naturalness of the objects in the garden.

Where a Japanese garden initially presents as wild and untamed, a natural expression of nature run wild, nothing could be further from the truth as Hohpe identifies.

It"s clear to Khurjekar that a Japanese garden accentuates the natural state of the elements in that garden and in doing so, imparts meaning into those elements as they are. This concept very in keeping with the Zen philosophy of the gardeners. The concept of accentuating the natural state and imparting meaning is known as the art of reduction.

What would an architecture aligned to this concept look like?

Flow Architecture embodies many of the same ideas found in the Zen garden. (For more on Flow architecture see the excellent article and book by James Urquhart)

Flow architecture advocates we represent our system as a series of nodes in a graph (rather than a stack), where each node contains its’ own context and properties separate from the whole. A node is designed (manipulated) to enhance the natural properties of both that node and the nodes connected to it.

The explicit design goal of a Japanese garden is to enable the viewer to observe all of the elements of the garden at once. If the individual elements are too big or too small they force the observer out of the scene entirely or make the observer zoom in so far that they lose sight of the broader picture.

Have you ever had a feeling when viewing an architecture diagram or document, that the level of abstraction is wrong?

How did that make you feel?

The Gardens of the Palace of Versailles

At the Palace of Versailles we see that nature has been reshaped in distinctly un-natural ways, that is to say, ways that are the opposite of what you might expect to see in nature. When I go hiking, I rarely see shrubs on the trail formed into perfect geometric shapes. Looking at the palace garden we see that nature is formed into shapes pleasing to the eye - aesthetics are still very important here, but instead of focusing on the natural qualities of the element, the element is shaped into a way that accentuates the un-natural construction of the garden.

To re-emphasise Khurjekars’ assertion:

Garden design in the Japanese tradition presents an alternative approach to the English tradition. The properties of the natural objects are not altered to suit an aesthetic design, as an ‘English garden’ designer might cut down a shrub so that it is neat and symmetrical, with the sole aim of pleasing the observer.

Robert Schwartz defines the French approach as “Order over Nature”.

Schwartz states that

Gardens are reflections of the people who create them. By shaping nature, men can exert control over their surroundings and create small paradises modeled after their own ideal of beauty.

Systems too are reflections of their creators and maintainers! Schwartz describes the gardens at Versailles as

The best representation of human will imposing itself on a natural landscape

And ties that into the nature of the designer of that garden, King Louis XIV

Louis XIV became an orchestrator, not only of nature but also of how visitors viewed this landscape. Even in the King’s absence, visitors would follow a specific path through the gardens, seeing them as he wished them to be seen. … As the Sun King, he imposed absolute control over nature, subjugating wilderness to his own ideal of beauty.

Bringing the French philosophy back to Architecture and applying this philosophy to the design of human and computer systems, the French approach is the approach the industry have broadly taken from the birth of the industry through to perhaps the mid 2000s.

The prevailing system design philosophy was one of control. Of planning. The Waterfall way of working emphasises clear boundaries between activity and a breakdown of process by function in an attempt to tame the chaos inherent in the large group hallucinations that software is.

This philosophical approach is that of The Architect of the Matrix, which Gregor Hohpe describes as

the ultimate authority: he designed the Matrix (a computer program to simulate reality to humans being farmed by machines as an energy source) and knows and controls everything. Enterprise architects are sometimes seen as such a person - the all-knowing decision maker. Some even wish themselves into such a role, partly because it is neat to be all-knowing and partly because it gets you a lot of respect.

Hohpe also warns of the master planned approach,

Even if the architect is a super smart person, he or she can base decisions only on those facts that are known to them. In large companies, this inevitably means relying on PowerPoint slides or statements from middle management as it is impossible to be in touch with all technology that is in place. Such an information channel to the supreme decision maker tends to be heavily guarded by people who understand its value as an influencing vehicle, which results in the architect being fed indirect, often biased information, as opposed to reality. Making decisions based on such a model is dangerous.

What can system designers learn from French and Japanese gardens?

When the Agile Manifesto took off, the change in how software projects are run became less about controlling the chaos and more about embracing it and redirecting it in the direction you choose - co-opting nature rather than fighting it, yet the root philosophy is still one of control.

Team Topologies seeks to organise teams and communication pathways such that they mirror the flow of value through the business - in other words seek the true value in what you’re doing and align around that rather than creating functional business areas that then struggle to work out how to pass parts of that value between each other.

In taking this bottom up rather than top down approach to system design, Team Topologies is closer to Zen then it is to Master-Planned.

In other words, rather then taming the nature of software development and imposing control over that nature, we now try to follow a more philosophically Japanese approach where we manipulate the organic properties of software development to enhance the naturalness of it.

Wardley Mapping also trends towards Zen in that it helps us identify the weeds in our system (those parts of the system that have already commoditized) Hohpe described earlier as well as Hohpe’s shade loving plants (perhaps accelerators towards value).

If the ways in which teams interact (Kanban, Agile, lowercase a-agile) slowly become more Zen-like in nature and less like we are all very small Sun Kings, the practice of architecture too must become more Zen-like. I see that change finally coming with concepts like Team Topologies , Flow Architectures and Wardley Mapping .

Software development as a group hallucination is best when it is creative, experimental, iterative and guided. Software development is inherently unconstrained in a way that e.g. hardware development is not. Our processes should manipulate that unbounded-ness and direct it in ways that enhance that natural beauty rather than trying to subjugate it.

In order for a system designer to build sustainable systems that work, we have to understand how value flows through businesses and how we should best structure the communication of that value. Having structured that communication we can design concepts around those flows and gently prune away the things that confuse or distort that communication.

We must act and design in ways that enhance the innate qualities of the elements of our organisations and systems. Doing so grants us the ability to place observers into those systems (customers, builders, managers, executives) who can see the system for what it is without parts of the system overwhelming others in that view.

That is why architects are gardeners and not master planners.

References and further reading

[1] The Software Architect Elevator Book by Gregor Hohpe

[2] enterpriseintegrationpatterns.com - Hohpes’ article on movie star architects that precede his book

[3] Gregor Hohpe - Gregor Hohpes’ website

[4] Japanese Garden Imagery by David Emrich - David Emrich on Unsplash

[5] French Imperial Garden Imagery by Hugo Ferrera - AXP Photography on Unsplash

[6] Formal Gardens - France in the Age of Les Miserables, Robert Schwartz

[7] Agile Manifesto - Agile Manifesto for Software Development

[8] Why is Flow Important - James Urquhart

[9] Flow Architectures - James Urquhart

I felt and still at times feel like fleeing to the woods to live as a wolf as a result of this realisation but I’m pretty sure my life insurance has exclusions for fleeing to the woods in order to live as a wolf. It’s not the family oriented response you think it could be, despite wolves being good family members that live in packs.

Anyway, these (broadly) are the steps I took to create my strategy, this article intends to describe systemically and procedurally, how you might create a technology strategy (or any other kind of strategy for that matter).

1. Identify the stakeholders to the strategy
2. Interview the stakeholders to understand the scope/expectations
3. Draft terms of reference based on the outcome of 2.
4. Present the Terms of Reference to the stakeholders and seek endorsement
5. Based on the agreed terms of reference go forth and gather data
6. Use Confluence to build out a template starting from the Terms of Reference
7. Link to relevant frameworks/models through Confluence for reuse via other strategies

Corporate Context

Eben Hewitt, in his book Technology Strategy Patterns , states:

In any business, there are patterns of work, at work within the business. These patterns are crucial to your success and their effectiveness may vary. Your job as a strategist is to understand the patterns and processes in your area of concern and use them to achieve your goals. Your job as a strategist trying to influence and create change will be vastly more difficult if you oppose these patterns and processes.

In other words, don’t fight the plumbing. Understanding and describing the corporate context you operate within significantly increases your chances of success. Your goal is to use the existing patterns to change the patterns. Don’t fight the plumbing, co-opt it.

Hewitt goes on to say:

The way to be successful in a company is to do something that matters to someone who matters. Projects that don’t matter to the people who matter are misaligned. Eventually, someone will ask about the line item on the budget spreadsheet. If nobody in the room knows what it is or why we’re doing it, odds are that it’ll be sidelined or cancelled. Aligning yourself with that project is a waste of your time and a waste of the company’s time. If you somehow manage to complete your misaligned project under the radar, you will soon find that your project was thriving only because it was under the radar. The impact to the company is once again a waste of time and resources as a result of the misspend, and a delay in the chance to complete the strategic stuff.

Your first job then is to identify the people who matter. This is nothing more or less than old fashioned stakeholder management. Stakeholder management is crucial to your success in developing a strategy for the reasons described above. If you are not aligned with them, you will struggle to produce value.

Determining Stakeholders

In order to achieve something meaningful, you must first understand the org chart and start at the top. Start with the CEO and the other members of your executive team. If your strategy does not matter to these people, it will fail. (Note that I’m writing this in the context of a smaller business. Fewer than 1000 folks but more than 50. An organisation where you as a strategy-maker would reasonably expect to bump into a random executive team member in the kitchen at lunch time once or twice a week. If your organisation is bigger, replace C-Suite member with a suitable director level role e.g. VP, Head of, GM etc)

There are three groups of people with whom you must be aligned:

• The folks who will pay for it and stand on a stage and tell others that it’s important (i.e. your leaders and executive team)
• The people who will execute it, and need to understand it well enough to execute it properly (the teams and individual contributors doing the work)
• The people who will ignore or undermine it if their views, aspirations or concerns aren’t represented (your peers)

You must have a 360-degree view of the organisation. That view will help you understand how your organisation works, how things get funded and where the bottlenecks might be.

Determining Drivers

Identify which leaders in the business matter in terms of your strategy. These people will reside across the organisation. They won’t be restricted solely to your business unit. It’s not enough to work in the context of a single function of the business. You will have to learn to communicate and collaborate cross-functionally.

Consider the different parts of the value chain your business implements (if you’re not familliar with value chain analysis - What is a value chain analysis? is a great resource) - Inbound Logistics, Operations, Outbound Logistics, Marketing and Sales and After-Sales Service (consider the supporting functions as well). Your strategy will not be the right strategy, and will not be supported or effective if you do not consult key leaders in these organisations.

It’s not practical to consult with everyone, and you should avoid rule by comittee. If you read anything in your strategy that looks like it could it might have come from a cat poster you saw at the dentist, it’s a sign that you’ve gone too far down that track.

Of the folks, you’re thinking about talking to, who stands out as powerful? Good leaders will try and make it look like they love all their reports equally, in reality, they do not. Reaching out to these people for their feedback and input has the additional benefit of making them aware of your strategy.

A fictional example, provided by Eben Hewitt in his book, Technology Strategy Patterns :

The mergers and acquisitions team might be two people in a room with no budget to buy anything and little of consequence to do. If the view is that building things ourselves is too risky and error prone, the M&A team might be very large and well funded (i.e. powerful) and busy buying another company every week. In such a case it’s important to consult with them as their input matters more. Your strategy should reflect that.

Stakeholder Matrix

Different stakeholders will have different roles in the context of the development of your strategy.

Create a list of all your stakeholders with two columns:

Influence

Influence refers to how important this person’s support is. What is their level of control over your destiny? Do they control funding or determine timelines or other constraints? How able are they to materially change the detail or direction of your strategy?

Impact

Impact refers to the degree to which, when realised, your strategy will impact them. If your strategy is to consolidate multiple products into a single product, your strategy will have a large impact on the sales, product and marketing teams. If you’re proposing we outsource software development to a third party, your impact on the members of the technology department will be extreme.

Score each stakeholder you know of on a scale of one to five for each column and generate a 2x2 matrix.

Quadrants

I really love the wording Hewitt uses in Technology Strategy Patterns to describe the different ways in which you should interact with folks depending on the quadrant they are situated within:

Monitor

Ask them on a regular basis how their work is going, and what’s coming up for them. Note what might inform your work. Check in occasionally about their work and yours. If these folks have a broader understanding of what you are doing and they understand why it can create support that may come in handy later.

Maintain Confidence

Invite them to steering meetings for your strategy. Send them updates on your progress. Be sure they understand the milestones and know how you are tracking against them. Ensure they understand and approve of your metrics for success. Ask them for insights that might modify your strategy. Follow up on their continued buy-in on your roadmap. Discuss your progress regularly and in detail.

Keep Informed

Invite them to larger forums for updates, such as town halls. Talk with them about work they may need to prepare, such as communications, training, departmental updates and so on. Go to their meetings to present specifically to their teams.

Collaborate

Actively work with these people on a regular basis in full partnership to co-create the ideas and execution plans within your strategy.

Setting Terms

Identifying stakeholders makes your life as a strategist easier. You have a list of people who care to different degrees, and you have an idea about what drives them, and the relationships they value.

The next job is to listen deeply to them. I call this process setting terms. The metaphor I use here is an investment one. Term sheets are an investment tool whose intent is to clearly outline the details of a deal. They describe the parties, they describe the agreement and they describe the investment.

You as a strategist are investing a portion of your life into the creation of this strategy. Creating strategy is a time-intensive thing, that time is very valuable in terms of salary, but even more valuable in terms of the opportunity cost. If you might spend six weeks creating a strategy - what else could you do with that time?

Providing a term sheet upfront, before you begin work in earnest will give you the confidence to know that you’re:

• Asking and answering the right questions
• Supporting the right activities
• Creating space for the right conversations

A term sheet is a powerful statement of support that will help you in the creation of your strategy. It’s a document that clearly articulates what you’re doing and why, and who your backers are. This can really help get traction with folks you need support from - it’s an instant way of helping them understand what you’re doing and create shared goals.

Collecting data via Stakeholder Interviews

Your next step is to collect the data you need to understand your terms of engagement.

With your stakeholder analysis, you have the information to know who your key stakeholders are. Your next step is to meet with those folks and listen to them.

The size and rough impact of your strategy will dictate how wide you need to go, as a starter, I’d book half-hour sessions with everyone who you have added to the ‘collaborate’ bucket. Time permitting, you should also interview all of the folks you’ve added to the ‘maintain confidence’ bucket. I don’t recommend interviewing either the ‘monitor’ or ‘keep informed’ buckets - there will be too many people in this group to interview and the resulting term sheet will be diluted by too many voices - strategy by committee is ineffective, so too are term sheets by committee.

What do I ask them?

Your goal in these interviews are two:

• Create confidence in the interviewee that you are listening, and that you hear and understand their point of view

• Find out the general and specific areas that your stakeholders want you to address in your work, as well as an idea of outcomes, how they might want your strategy to be implemented as well as their preferred way of interacting with and understanding your strategy

• Here are the questions I asked my stakeholders:

• What do you need from the digital strategy?

• What are the key points you want the strategy to address?

• What kinds of concrete outcomes or activities should we be able to derive directly from strategy?

• How do you want to feel after having read, been presented or otherwise consumed it?

With the raw data from these interviews collected, you can begin to boil it down into terms. You may have to go back to clarify several times. You may have ideas from stakeholders that clash or are incompatible. That’s okay! Add them to the terms regardless. One of the benefits of this document is that it will make clear where your stakeholders do not agree, the terms will give you an option to work through and solve that disagreement in a neutral and unbiased manner. At the same time, going through that process with your stakeholders will build trust - trust is a critical resource for you to manage.

Closing on the terms

With a draft term sheet in hand, your next step is to get agreement. Your end goal is a meeting in which all of your stakeholders express that there is nothing particularly controversial or bold in the terms and that it all makes complete sense - it’s the natural thing to do!

That’s not to say your terms aren’t radical! The strategy should be strategic! The point is that by the time you get the final meeting to ratify the terms, all of your stakeholders have seen them a few times. They see themselves in the terms as a result of your interviews with them. They see the needs they express are being met and even some needs that they didn’t express (helpfully their colleagues expressed those ones!).

There shouldn’t be much discussion at your final meeting. You should open by reviewing the terms and the process that got you all there, and then ask for ratification. The meeting should feel like a fait accompli.

How is this possible? You should be having the meeting before you have the meeting.

Book a second round of meetings with the stakeholders you initially spoke with, and brief them on the term sheet you’ve developed. Use this time to pay attention to their individual needs and answer any questions they might have. This is a good opportunity to road test your ideas and ensure that you have drawn the right conclusions, and synthesised the many different angles of feedback from your stakeholders appropriately. For more detail on pre-meetings, see When it's worth having the meeting before the meeting fair warning, it’s HBR and very American.

Building your strategy

With a group of folks behind you and an agreed outcome, the next step is the fun part! Now you get to create your strategy and show your vision, knowing that the whole business is behind you and wants you to succeed!

I believe that good strategy has two key jobs:

1. Share Context
2. Make Assertions

The goal of a strategy is to clearly articulate a situation and plot a course through it. The nature of any strategy is that it is actionable. It guides us. In the same vein, every statement you make should be falsifiable. The thing that differentiates strategy from vision is action.

Your strategy should primarily consist of assertions. With the full body of context behind you, you can draw a clear line between the context you observe and your assertions about how to respond to that context.

In other words, the contents of your strategy and the points you address are defined by your term sheet. The way that you respond to the term sheet should be informed by the context. That response is your strategy.

The specifics of how you write and communicate your strategy are entirely up to you, and I offer the following advice:

• Keep talking to stakeholders, be visible in what you are doing and seek feedback throughout the process
• Your strategy should be practical. It should be easy for folks to read it and answer their own questions about what they need to do. The reader’s next steps should be clear to them.
• You can make those next steps clear, by making clear assertions that are informed by context. These may take the form of “Given X, we should Y, therefore we need to Z.
• With your writing, you should be optimising for the reader. Optimise for them, their time, the way they break down and understand information. Optimising for the person reading your strategy is much more difficult then optimising for the writer!

Documenting your strategy

Regardless of the content of your strategy, it’s going to involve words. Knowledge. Ideas. These things will evolve and grow over time. You will need to store these things somewhere visible and accessible, searchable and editable. You will need to engage in conversation pertaining to specific things you have said. You will need to demonstrate that you are listening and adapting to feedback.

Your company’s knowledge management solution is the place for this. Notion, Confluence, find a space or create one, and put your strategy there. Your strategy being words, will be wordy, and few people may want to read all of it. That’s okay. You’re creating a reference.

Once you have strategy published and it’s some degree of complete, you’ll be able to create products from that strategy to suit the audience and the message.

Consider the words in your knowledge managent solution like a big bowl of dough. That’s a lot of calories. It’s big, carb-heavy. Could take some time to get through in it’s current form. Sweet Jesus that’s a lot of calories. With this documentation you are creating an encyclopaedia for folks to take what they need. We don’t expect anyone (except my seven year old becuase he loves it) to take the encyclopaedia from the shelf and read it from start to finish in one sitting.

Presenting your strategy

You cannot ask sixty people to sit on a teams call and listen to you read out loud, no matter how velvety smooth your voice is. When it comes time to present your ideas, take a slice. Cut off a piece of dough and shape it and bake it however you need.

In this case, I would recommend a slide deck or shorter written summaries - think flash cards, not short stories. You can create as many slices as you need, that target and speak to as many audiences as you need, to any level of time. Having the full strategy written and held elsewhere makes it infinitely flexible when it comes time to present, and that is a very powerful capability to have in your back pocket.

There are two facets and five cuts you might like to consider as default options. Pick one facet and one cut, and you have a purpose built communication tool specific to your audience and their context.

Facets:

• Technical
• Non-Technical

Audience Cuts:

• Board
• Executive Team
• Department Managers
• Entire Department
• Entire Business

To produce individual decks addressing all of the combinations of facet and audience is made much easier by having the complete documentation live elsewhere. It becomes a case of pulling the relevant data and message into each deck - and there is no need to do them all at the start, it takes so little time to recast that you can do it as needed, rather than upfront.

Implementing your strategy

This section is left intentionally blank, as an exercise for the reader.

Summary

Creating strategy is hard work. Implementing it is harder!

Your strategy will live within the corporate context of your organisation. It will be dictated by your organisational design and the individuals who fit within that design.

You will need to identify the folks who matter to your strategy, and win them over. Further, you’ll need to manage stakeholders with varying goals and varying centrality to your strategy, and you will need to work with them and their processes, not against them.

Consider that in writing your strategy you are creating a desk reference on where we are going. Expect to take that volume and streamline it for the time, place and audience - and optimise for them, not for you.

References and further reading

[1] Technology Strategy Patterns - Eben Hewitt

[2] What is a value chain analysis? - Tim Stobierski, Harvard Business School

[3] When it's worth having the meeting before the meeting - Andy Molinksy, Harvard Business Review

[4] MECE - Wikipedia

R E V E N U E

Software developers, and technical people of all stripes, for that matter, have the same role that every other employee in the company has. Solve problems for customers that customers will pay for. Do so sustainably, do so responsibly, and do so ethically. All of our roles exist to bring value to the customer and bring value to our teams. That’s it. Spoiler, that’s the essence of the entire article.

It’s important to note that I don’t mention writing code. We’re not talking about APIs or Microservices. Databases? Design? Don’t care. These are tools that we use. The same way that Vic on the social media team uses short-form content to inform folk of the value their company brings. Just like we collaborate to build a marketing website or a CMS. Just like the fine folks over in finance, we make sure we can be sustainable in the value we bring to customers so that we can continue to work away at those problems.

Increasingly Customer Focused

It’s no accident that over the past few years, as a collective, we’ve focused on bringing back-office functions forward. Even five years ago, sitting in front of a customer to talk about something I’ve built would have terrified me. What if they don’t like the software? What if they noticed that bug I couldn’t fix in time? If you haven’t ridden the “Oh no, they’re on the page with the column that’s three pixels out” roller coaster, are you even a thrill junkie? They didn’t even notice that side of the page because they were focused on the cart.

Getting back-office staff (technical or not) out in front of customers has driven innovation and improved the quality of the products we create. The empathy that we feel for our users has grown. I used to have a CEO that said, “I don’t need to pay for design staff because we’re a monopoly. Our users will use our software anyway, so it doesn’t have to be good; it has to work”. Inspiring stuff.

Ultimately, with any for-profit enterprise, this comes down to money. These techniques produce better outcomes for the humans that pay for them. Better solutions mean more revenue, better retention, and so on. On an individual level, I like to think that we here care more about the people involved than the dollars. We here are deeply passionate about producing something extraordinary that improves people’s lives, but I may just be projecting!

Getting out in front of customers, engaging with other parts of your business and generally getting away from your desk a bit more brings opportunities.

Being close to the customer reduces rework. If you know well what people want, it’s easier to identify that we’re building the wrong thing or that the thing is being built in the wrong way.

Talking to customers is also a great way of getting early feedback, and the benefits of more rapid input in the software we make are well known. It’s easier to stay aligned as a team, and it’s easier to work with product and design folks because of that alignment. Being close to the customer is like greasing the wheels that way.

Is career progression important to you? Being close to the customer cultivates trust with the broader business because you’re not just those speccy folks that want to talk about RAM and AZURE. You’re the people closest to the customer. You demonstrably care about and advocate for your customers. Those above us who make decisions about us and our careers will see and reward that.

AFK

This brave new world does bring challenges. The big one is time management. Time away from keyboards is valuable - but there are already reasons for us to be away from our desks. Meetings are the most common complaint. Reviews, plannings and refinements. Sitting with stakeholders, sitting with customers, general admin. Sometimes it feels like we already spend more time talking than doing work.

It can be pretty demoralising if you measure your productivity or worth by lines of code or the number of releases. Lifting your head and treating time away as an investment in creating better (if fewer) outcomes can help with that. Better still, judge yourself by the impact you make, not by any technical metric.

Parting Thoughts

The next five years are looking good for us. We are people who produce solutions for customers through code, and in that space, demand will exceed supply for quite some time. With trends like DevSecOps, we’ve seen teams of specialists turn into cross-functional teams. With design thinking, we’ve seen groups of people who previously thought they had nothing to do with a customer’s experience realise that we all have an impact. That impact might be a workflow in an app or the pricing model we sometimes inflict on users. Self-sufficient, sustainable product teams are becoming more common. Business people who in the past didn’t have a lot to do with the software are becoming more involved, and groups of technical folk are gaining access to more institutional knowledge, better links into the business and faster feedback loops.

So what do I say in parting? You are not the code you write nor the technical solution you create; that is immensely positive! We’re seeing people begin to value us as complete humans, not as mechanical turks running on undersized EC2s that produce software. We’re seeing that the IT Crowd is now a comedy show and no longer a manual on what to expect from technical staff and how to treat them. With that comes leverage for us, personally and professionally. Think about how that leverage applies in your role and use it! Use it to get better outcomes for the people you create for and better results for yourself!

The IETF has published a document detailing the QUERY verb. The Query verb neatly solves the problem of asking APIs for LOTS of data or conditional data. In other words, QUERY enables API providers to provide a means for clients to ask the server about data, where the client isn’t sure what data is available.

A worked example

Working in Agri-tech, I often want to find out information about animals. Unfortunately, that information can live across many systems, with many identifiers (primary keys or other). In one context I’ve experienced, Dairy Animals can be identified and referenced by five or more different identifiers - so what do you do if you don’t know all of them?

In my case, I want to provide an API with the identifiers I DO know and ask for the API to return any identifiers it has that are linked to the ones I submitted. There are a few ways the API could implement such functionality.

For a complete animal:

HTTP GET /animals/${the_identifier_i_know}?identifierType=${the_identifier_type}

Based on this request URL, I would expect to provide an identifier and receive back the entire animal entity. Animal entities can be of substantial size! Serialising all this data can be time-consuming and wasteful for a busy API, particularly when we know we’re just exploring and want only a subset of that data. We’d be discarding 90% of the data returned.

For an animal’s identifiers only:

HTTP GET /animal/identifier?identifierType=${the_identifier_i_know}

I interpret this URL as only providing me with identifying details about the animal. Optionally, I can request a certain type of identifier. If I only care about a singular animal, this is probably all you need. No QUERY verb is necessary. What If I want to query a collection of animals? There are potentially many thousands of animals in a group for which I require data. I’d encounter a significant HTTP overhead, making that many requests to this endpoint. What we need is an API for a collection of animals!

A collection of dairy cows is a herd. I don’t care about herds; I want identifiers for an arbitrary group of animals for my specific use case.

REST guidelines ask that you model your APIs as

/{collection_one}/{collection_one_identifier}/{collection_two}/{collection_two_identifier} and so on.

Under this guidance, we cannot submit multiple identifiers for a single collection. So if we had 3000 animals, for example, the request might be:

/animals?identifier=id1,id2,id3 ... etc - it doesn’t make sense! Putting many identifiers in a URI comes with its work, but crucially, if you’re asking for lots of data and are forced to encode that in the URI, you could run into length limits preventing you from encoding all of your request. Most servers will typically limit the length of your encoded URI to 2048 characters or less. Those servers will decline your request if the URI is too long.

Most folks get around this by defining a POST endpoint that breaks RESTful principles. Here’s an example of a POST request:

HTTP POST /animals/search with a body:

{
  "knownAnimalIdentifier": [
    "id1",
    "id2",
    "id3",
    "id4",
    "id5"
  ]
}

You could put all sorts of freaky logic or conditionals in this body; there are far fewer limits and, therefore, more risk of pushing the concept outside sensible boundaries. For example, this might also be valid:

{
  "knownAnimalIdentifier":[
    "id1",
    "id3",
    "id3"
  ],
  "where":{
    "healthTreatment":{
      "condition":"mastitis",
      "product":"amyzin"
    }
  }
}

You could pull all sorts of stunts here. The above looks suspiciously like GraphQL to me - the key message here is that POST-ing arbitrary search data to an API imposes very few limits on otherwise conscientious and responsible developers.

Further, using a POST doesn’t match the intent of the request. REST guideline defines a POST as NOT idempotent - POST means you’re creating a new resource every time you make the request. With our above requests, the intent is to search for data, not create resources, but we don’t have a good way of modelling that! You could argue that when you submit a search via POST you are asking the server to create a new resource containing your results - the issue with that, is that you’re not creating a new resource. At best you are creating a new projection of resources that already exist. You’re not POST-ing a new letter into the letterbox, you’re asking the mailman to pass you some letters that may or may not exist.

To do a search we need to do the HTTP GET POST GET dance. First GET enough data to formulate your search query, then POST to create a query resource, then optionally GET the resource you just created.

Some folks will implement an API that directly returns the results to you. You’d need to code for latency, dropped connections and retries. For long-lived queries, you’d need a solution for the underlying data changing as the query progresses (similar to pagination where page 3 changes after you retrieve it but before you complete paging). If the API indirectly returns your data to you (i.e. immediately returns a link to the newly created search result resource), you have to go and GET that resource.

Using POST requests for search functionality solves one problem - lack of flexibility in the GET verb - but introduces another. Using POST server cannot cache or re-use results, nor can it deal gracefully with common failure modes (retrying ten times creates ten resources! All those resources might be different!)

The Query Verb

Julian Reschke, Ashok Malhotra and James M Snell has authored a draft RFC that describes the QUERY verb .

QUERY solves the problems of your typical search workflow.

The draft spec defines a QUERY as a means of making a safe, idempotent request that contains content. It’s worth your time to read the entire article (it’s about a five-minute read).

The important parts for me (i.e. order and emphasis mine) as a system designer are:

QUERY requests are both safe and idempotent with regards to the resource identified by the request’s URI

The response to a QUERY method is cacheable

The body payload of the request defines the query. Implementations MAY use a request body of any content type with the QUERY method, provided that it has appropriate query semantics.

The payload returned in response to a QUERY cannot be assumed to be a representation of the resource identified by the effective request URI.

Before, I would have to make a GET to some URL with an enormous query string OR create arbitrary numbers of un-cacheable new resources; now, I can use the QUERY request. Furthermore, I can put whatever data I need in the body of my request, safe in the knowledge that implemented to spec; I’m going to get a quick response that I can cache in line with the server’s guidance.

It’s a small and subtle change. Implementation-wise, you could change your existing POST search endpoint to a QUERY and leave the same body. Migrate current GET endpoints by shifting query/path parameter content into the body and change the verb.

The most significant improvement relates to intent and clarity. Using a QUERY verb signals my intention to request data based on conditions that I supply. QUERY marks that request as idempotent and indicates the intent of the caller.

POST shows intent to create a new resource. GET indicates intent to retrieve a resource for whom the caller already has an identifier. Neither POST nor GET indicate an intention to request data about which the caller is uncertain. The semantics of the verb and the request matter because they clarify intent. Computers will do what we tell them to do. Not what we intend for them to do.

Clarity of intent in an API is crucial to the success of that API. When designing that API, we want to make it as easy as possible to map the intent of the caller to appropriate functionality in the API. Introducing new verbs to clarify the caller’s desires and better match those needs (i.e. “What endpoint should I call to do X?”) to the correct part of an API brings developers joy.

Conclusion

The QUERY verb is brand new and in draft with the IETF - you can check it out here . It clarifies the calling system’s intent and enables behaviour more suited to interactions where you don’t know what specific resources are available, but you do know something about those resources (e.g. the first and last names of a person, or their phone number, email address or some combination thereof). QUERY allows for idempotency, caching and is easy to adopt incrementally.

Citations and Further Reading

• Julian Reschke, Ashok Malhotra, James M Snell: The HTTP QUERY Method

What is a 1-day sprint?

There’s nothing fancy about a one day sprint. All it is, is your regular sprint cadence scaled down to eight hours. Of course, that means your rituals scale down as well. In my case, a one day sprint meant a half an hour planning session in the morning before we kicked off into work. If your regular standup is meandering, not resulting in a plan for the day or is otherwise less effective, then you might hope this is an excellent way to fix it. The broad idea here is, as John Cutler says, to have the conversation and then do the thing. See John’s article here .

Timeboxes are a forcing function. Forcing functions help you control things you want to control. Setting a timebox of one day for the sprint acts as a forcing function for the size of the work you bring into the sprint. Setting a timebox is also a forcing function for the amount of work you pull into a sprint. If you want to deliver a successful sprint at day’s end, you need to be careful about the shape of the work you commit to, as well as the amount of work you pull in.

Small timeboxes lead to chunking down work smaller. Your larger work items won’t fit, so they need to get smaller. The process of breaking down those larger items forces clarity and understanding. Where before you might have a big fuzzy thing you want to deliver in two or four weeks or longer, you now have to split it up and to split it, you need to understand it. So, the small timebox also forces a better understanding of the work you are doing while removing all of the places uncertainty usually likes to hide.

In other words, you never have to worry about whether or not you can get something done - if you don’t think you can achieve the work in a day, keep talking and cut it down smaller. Worst case, you might spend most of the day talking, that’s okay. Planning and breaking down work is a universally valuable thing. Your company pays you to produce solutions to business problems, right? I’m assuming you’re not paid per line of code written per hour.

What made me think 1-day sprints would be useful?

(a.k.a. how can you identify when they might be helpful to you?)

I had an excellent experience with 1-day sprints on one team and projects that might not translate to another group with different constraints.

For context, I had a project that needed to be done by a specific date. We got approval to start the work, but by the time we could pull a team together, we would only have eight weeks, give or take, to build and deliver the tech (We delivered in six weeks).

The project was a challenging task mainly because of the available time rather than because the solution was novel or the technology complex. We had to deliver our solution and enable our partners to integrate with our solution simultaneously.

I identified early on that I had two important jobs that needed to be done.

I needed to:

• Hire a process that enabled the team to be highly responsive to the progress we made, and
• Do that in a way that provides clarity and transparency for our external stakeholders such as the CEO, CIO, and sales folks working with partners who want to use the solution.

The default process we use is a 2-week sprint. We had eight weeks to deliver the solution and clear instructions that if at any time we felt we wouldn’t hit the timeline, we should stop. Sharing progress with stakeholders four times before the deadline would not be good enough. Bugging teams about progress every day would negatively affect the team.

Running a 1-day sprint would yield 30 reporting opportunities rather than four. 1-day sprints constrain us to work that we could reliably achieve before the next reporting boundary, ensuring we would always be able to report progress. Making that reporting interaction a system feature rather than having an individual do it would also protect the team from undue interruption and help them maintain flow - increasing our likelihood of success.

I hired 1-day sprints to enable decision-making and reporting agility, both in and outside the team. We saw some other benefits. In the first week, we created significant momentum. We were better able to onboard new team members since the work led to making the smallest change possible. We quickly encountered, identified, and resolved bottlenecks because the moment a 1-day ticket didn’t take a day, we knew to stop and inspect.

Using a 1-day sprint created momentum and flow.

Using a 1-day-sprint also created clear intervention points where momentum and flow broke down due to missing tools or processes.

Because we could so rapidly diagnose and resolve issues affecting productivity, we were productive. Further, because we could respond quickly, a little bit of pre-planning went much further than it might usually have gone. For example, we identified some third-party dependencies early on and encountered delays with some of them. Our ability to respond and work around those delays meant that those delays did not become blocking issues where a team running a 2-week sprint may have become blocked by them.

Some other (unscientific) observations:

• The team that ran 1-day sprints had an average cycle time of about three hours.
• Our average time to resolve a blocking issue for our integration partners was about 24 hours - addressing these issues rapidly in a 2-week sprint would be disruptive and affect sprint scope. We didn’t have that issue with 1-day sprints.
• The team enjoyed working with 1-day sprints. They rated the experience at 4/5.

Risks

We did highlight risks through our regular retrospective process. There are things to think about and tradeoffs to make.

Make them deliberately and with forethought:

• Managing wellbeing can be tricky. Running sprints for a long time can lead to burnout. Folks need mental breaks. We usually build in time to recuperate (in the form of quarterly plannings, offsites or other regular “off-sprint” time) - that time can be harder to lock in with a 1-day sprint.
• Managing dependencies, blockers, or long-term plans requires thought. It can be tricky to map tactical activities up to operational or strategic activities. To address this tradeoff, you’ll need to draw lines between your day-to-day and your strategic efforts more often.
• It’s weird - 1-day sprints can be novel for many organisations. If you want to run a 1-day sprint, how does that process interact with other parts of the business? What about the governance and finance folks? Customer support? Does pushing out small batches of work every day put a strain on other parts of the organisation? Does it expose and break manual processes we might have in place? Dunno. The impacts are worth thinking through.

Conclusions

1-day sprints are a potent tool - they can help you turn around a team struggling to complete sprints and circuit-break uncertainty in the development process. In addition, 1-day sprints can help you restore confidence with stakeholders and rapidly build confidence where you don’t have a lengthy pedigree to stand on. As with most tools, this carries risk, and there are questions you’ll need to answer thoughtfully to make the most of 1-day sprints. What are your dependencies, and what impact will such rapid feedback have on other parts of your system? While 1-day sprints may work well for the team conducting them you should also be mindful of their impact on other teams. Will working in 1-day sprints place extra pressure on your colleagues? Is that pressure a feature or a bug? It’ll be up to you to ensure that pressure is positive!

Sources and Further Reading

Any organisation that designs a system (defined broadly) will produce a design whose structure is a copy of the organisation’s communication structure.

— Melvin E. Conway

Introduction

Team topologies are a concept created and popularised by Manuel Pais and Matthew Skelton. They describe a way of reforming your organisation shape in such a way that improves the architecture of your software while reducing cognitive load and directing more energy and focus towards the streams of value that flow through your organisation.

Performing an inverse-Conway manoeuvre is a big deal. We’re talking about people’s livelihoods here. To do it, you need to collect skills in change management, communication, design, and potentially many more things. Critically you’ll need to figure out the communications pathways and relationships in your business that will get your plan actioned. You’ll need to figure out the logistics behind the action as well. If you can do that, you’re golden.

Those top-level streams of value are paramount. Getting them right helps your design resonate. It helps you build shared understanding. It helps you account for change over time and growth. Streams are flexible by nature, but it’ll help if your streams make sense from the start.

To do this, you’ll need a team behind you. More than that you’ll need friends. Folks who come together to work towards an answer to the questions:

Why am I spending so much time fighting my architecture? How do we build a sense of ownership? How do we balance short term priorities with long term strategy?

I’m going to talk about how my org did it — an org that is large by New Zealand standards but small globally.

I’ll walk you through the symptoms we had and how my org struck at the root cause, how I developed an idea and worked to get it signed off. I’ll finish with how we’re rolling out that change and offer some advice for you to takeaway.

One time I cooked two-minute noodles in 112 seconds, and that was pretty cool. This is much cooler.

Symptoms

In our technology department, we used to be extremely busy. We still are, but we used to be, too. We had various streams of work in progress such that every ten weeks, all of our teams would end up working on something different to what they worked on in the previous ten weeks. High WIP made things difficult to manage, and it caused us pain.

Teams could never really “own” a bit of software for longer than ten weeks. We couldn’t build tribal knowledge because we chopped and changed regularly enough that by the time we returned to something (if we returned it at all), the expertise we gained prior we lost to skill fade.

Mostly we took one pass at solving a problem for someone and never got to iterate on an issue. Our teams were (and still are but to a far lesser degree) funded on a project basis, and the project already had a tick in the box.

Because we never iterated on our work, we never returned to address technical debt. We never got to enhance successful features nor swing around to flourish the scythe at poorly performing features.

Knowing we would never return, we would oscillate between gold plating our work (and delivering late) and piling on technical debt (which would cause late delivery and more down the track instead).

Never returning leads to ’ninja teams’ that are typical firefighters who do an excellent job of tackling small urgent work but struggle to create features of substance. This type of work focuses on short term aims and optics at the cost of long term progress.

Knowing we would never return, our stakeholders would ask us to reduce our estimates and do more work in less time. Or worse, ask us to cut non-functional work or work that other projects relied on (also, we had dependencies between work that ought to have been independent).

None of our teams had distinct specialities, focus areas or parts of the architecture they resonated with or cared for.

It was expected that to deliver a unit of valuable work to a customer; an engineer would need to work across 5+ codebases, 3+ languages, queues, streams, containers, lambda functions or services deployed on bare metal.

The cognitive load across these tasks precluded us from developing expertise. The footprint of our architecture relative to our level of staffing trapped us in a place where we could never gain or retain enough proficiency to deliver to our partners and stakeholders’ expectations.

Our engineers did a great job of treading water — but they should never have had to do that! We as leaders put them into a place where systemically, it was an effort to remain in place.

With continually increasing demand from our partners across the organisation, we couldn’t keep doing this. Not only did we need to staff up. We needed to organise ourselves better. We still do, but we used to, too.

What is a Team Topology?

Briefly, team topologies are the answer to the question, “How can I reshape my organisation to be more focused on the streams of value that flow through my business?”. Developed by Matthew Skelton and Manuel Pais, team topologies gave me the tools to describe what I felt needed to change in my org, be more focused on value, focus on products, and focus more on teams and streams of business value.

Team topologies are about optimising for flow and reducing cognitive load of all kinds. It provides a ubiquitous language to talk to anyone in our business about value, interactions, and what it might look like to evolve our organisation humanly and humanely.

If you’re not familiar with the concepts and have some time, I highly recommend you have a quick read of the website

Team topologies contain four basic topologies — stream aligned teams, enabling teams, complicated subsystem teams, and platform teams.

The fractal nature of these streams allows for growth. They also enable incremental adoption — this is a critically important factor for my enterprise, and I imagine others will find the value there as well.

As a concrete example, right now, we have one platform team, my team. Our platform team needs to support cross-cutting concerns over a business of many hundreds of staff and many development teams. We have a backlog that’s about four years long, and we’ve existed for four months.

That’s okay!

I’ll expand on this more later, but as buy-in grows, we can hire more teams to work in the platform space, and we can start splitting our platform space into streams of the value of their own. I.e. right now, we have one platform team; in the future, I expect we’ll have an animal platform team, a customer platform team, et cetera. They will one day cover all of the valuable parts of our domain where cross-cutting concerns exist.

Teams interact with other groups; often, it’s not clear how or that how is not a considered (even conscious) decision. Out of the box with team topologies, you get three modes for how your team should interact.

Why Team Topologies?

Team topologies, an extension by the same authors on DevOps topologies (links below), is well-researched, well-cited, and the adoption is snowballing. It’s cutting edge, and it directly answers the pain my organisation felt.

It’s not the case with all frameworks or concepts someone will try to sell you, but team topologies directly address the root issues of that pain as well!

Some of the frameworks or concepts that I’ve read about seemed fluffy, difficult to apply to the real world or hard to implement. This is not the case with team topologies. I found it easy to re-model my organisation on a whiteboard. I found it easy to grab the nearest available executive (who happened to be the CIO) and talk through what I was thinking. We both found it easy to talk about what it might mean for us, how we might start it, and how we might measure how we are doing.

I rolled my whiteboard around the office and shopped it to different parts of my organisation, and each time I was heartened to see folks intuitively grasp the ideas. Because the model was simple, the ability to give feedback on the whiteboard was very accessible.

In this way, it was easy to get buy-in on the strength of the idea.

That ease put folks at peace while also enabling them to research for themselves; it cemented the ideas as credible and actionable. Even better, we had a clear place to start with rolling out a platform team focusing on our API platform that interacted in a collaborative and sometimes as-a-service manner. The API platform team was a great first team, and we could use it to build comfort and familiarity with the system. We could use that platform team for prototyping the wider rollout. We could roll out incrementally, starting with a top-level team for our API platform, and then convert existing units into top-level teams for their streams. We could later split those streams and add additional humans who would be more tightly focused on their fractal streams.

The ability to roll out incrementally is a crucial enabler. It means we don’t have to invest millions of dollars — we can change the org like we change software, quickly, adaptively and responsively. We don’t need to ask for an infusion of trust and an investment of money — we only need to ask for the first team and then show what we’ve measured and learned.

Incremental rollout is easier on the rest of our business function as well. It’s easier to hire, onboard and retain small numbers of staff. It’s easier to help those staff build relationships across the business, and it’s easier to track how we’re going — making it easier to ask for the next team and do it all over again. I can’t stress enough how critical this aspect of team topologies is for our business.

This low-restructure (frankly, you can never guarantee it) approach stands apart from more traditional ways of defining and creating a system of humans. I love it because of the degree of humanism I see in it. Nowhere in team topologies or any of the conversations around it do I hear humans referred to as resources.

The Process

Most organisation change is long-lived. It can be messy. It can be difficult. Humans are prone to making mistakes. We’re inclined to miss things. Before I asked my colleagues and friends to embark on any change, I needed a clear, shared understanding of where the organisation is at.

For my organisation, this meant defining what teams we have, what they are working on, how they act and how they feel. Do we have the coverage we need to support all of the software running in production? Are teams happy and healthy? Is there anything that’s causing them pain right now?

Defining these things on paper, visually rather than with paragraphs, is a forcing function for clarity and understanding (if folks can see it on a whiteboard, they’ll tell you when you have it wrong).

In my case, I saw teams that wanted to gold-plate solutions; we (systemically) had piled them high with code they would never have time to maintain. We asked them to context switch on an almost daily basis. Making a single change in a product could require changes in many supporting systems. This did not spark joy.

We knew the power of teams that cover vertical slices and focus on delivering incremental improvements to our customers, but our domain is complicated, and our architecture is large. A number of us across the technology department sensed (and still feel today) that only having vertical teams in a domain as complicated as ours, holds us back. They needed support.

We burdened teams with too much cognitive load. We asked them to take on so much intrinsic and extraneous cognitive load that they had very little thinking space left for the germane cognitive load!

We struggled through our symptoms, and credit to the teams — given what we asked of them, I think they did a great job. I think we treated them unfairly.

The Enemy of Art is the Absence of Limitations

Orson Welles

Our situation felt dire when catalogued this way — but constraints breed creativity. It took some research, but I eventually discovered the ideas Matthew Skelton and Manuel Pais had packaged up as “team topologies”.

I spent about a week on my initial drawings. I spent another three refining my ideas with the feedback of anyone who chanced a walk by my desk and everyone who had five minutes for a chat that inevitably ended an hour and a half later. I filled up 3.6m x 5.4m of whiteboard area — 20 square metres if you round up. The digital versions are far tidier (full credit to an excellent UI designer named Luiza) and more compact. I’ve inserted them below.

There are a few caveats here — this isn’t the final concept we went with. It took further refinement at the exec level, we had to make it fit into the financial model of my org, and we had to think about the types of skills we needed in each team.

Additionally, while the work the images captured above were all mine, we had an existing strategic plan for technology, and had spent a lot of time fulfilling that strategy — the work that I had done fed into these plans and offered language, context and shape to what we already felt we had to do.

At a very high level, I produced an organisational design with both vertical and horizontal teams, where all teams align to a stream of value. My organisation already has business units aligned around the value that we bring, as you’d expect. So each business unit/stream gets a top-level team initially. I designed these teams to be overwhelmed, and I expect them to have a long backlog initially. Once they’re up and running, the most valuable work or critical systems should naturally bubble up to the top of the backlog. The key for these teams is to remember they don’t need to boil the ocean, only demonstrate how we all work together.

I thought that once top-level teams are up and running, and work is being done, the next large job is to begin planning for additional teams. This means doing the work and getting value out to users. It also means using the demand in the business and bubbling up of work in the backlog as signals to identify fracture planes in each stream of value.

You can align streams of value in several ways. I don’t think there is any single way to do it. My org has streams of value that map to workflows in our products, to user journeys and platforms like mobile and web. I’m currently aligned with the top-level team of the API platform. One day, I’ll start cutting that up into streams about animal data, scientific processes, customer data, authentication and authorisation, or more. Nothing is true; everything is permitted.

This structure addresses most of the pain I had identified and validated. This structure is by no means perfect or final. I don’t believe there is such a structure. It seems clear that as our organisation grows and our needs change, we’ll need to revisit our design. The good news is that aligning to streams of value means that we can modify the way we are shaped by applying or removing teams from value streams.

One key issue that this structure does not address — and it’s worth stating explicitly — is product or value stream funding vs project funding. Arguably, many of the challenges we have had are directly attributable to our organisation being funded for discrete projects and not long-lived products of value streams. This discussion isn’t one I want to spend much time on because team topologies are distinct and separate concerns. To a degree, we can map incoming projects to streams of value, so it’s not a huge deal now — though it certainly was before we were able to map stop/start work items onto long-lived bits of software.

A critical pivot point for value stream vs project funding is addressed by my model in that I’m advocating for a far greater influence in our system for product people. Each team in my design contains either a product owner, or a product manager, or both. Product folks should proactively engage with the wider business and collect all of those would-be projects and map them to products. With time I would expect to see the number of projects coming in from the wider business reduce as we scoop up increasing amounts of work and drive from within the technology department.

With some whiteboards to focus conversation onto ideas, the part that I struggle with most is next — communication. I’m not great at packaging what I’m saying for different audiences; I’m not proud to say that I’m responsible for more than a few phone calls between executives!

Communicating well what your model looks like, what it’s optimising for and importantly, what it’s not optimising for is the bread and butter of getting this change across the line. Your organisation will be unique in this area — it comes down to people. Who are the people you need to show this to? Whom do you need to convince? Who can you recruit as a signal booster to get your message into parts of the organisation you don’t have access to?

I probably spent the better part of 100 hours talking about this to people, taking feedback and refining the message, format and substance. Once I started hearing people talk about this in reference to other issues they’ve encountered in their work, I knew that they got it.

The next step was to do it. Both intimidating and exciting, it was time to turn the model into something tangible. Again every organisation will be different and have different levers. For my org, it was a mixture of strategy and finance. I had to convert this arbitrary concept I found on the internet into something that our leadership team could act on - that meant turning whiteboards into the same shapes that go into our budgets, with the same language we use in our strategy documents.

Something that helped a lot was to frame this idea in the same language we use today. Department leaders and I spent time collaborating on the next version of our plan. This plan was an extension on what was already occurring, and would help us scale effectively from five teams to more than fifteen! My input in this process was language and shape. The streams, the teams and the meaning behind them became a part of our strategy and a part of our plan. That input morphed from being a single data point to being “just the way we do things”. Importantly, this collaborative process made it easy for all of us to tie the benefits to current opportunities we had to improve on.

At that point, we had a plan that looked budget-able if you squint at it. We had a plan that we felt would give us room to grow while addressing pain and history. We published the idea in the relevant documents, and the machinery of the organisation swung into action to analyse, approve and implement.

The critical take away here is this: Don’t fight the plumbing. Co-opt it. Redirect the ship from the bridge, not the bow.

The Rollout

My organisation started with just one team, responsible for the shared core. The idea being we start slow and take the time to get it right. Team interaction modes, the way we embody the agile manifesto, the way we apply software product management principles, and how we collaborate to create technology all need conscious thought and planning. Importantly, all of the ways the team come together to deliver value also need road testing. We planned to work in very different ways compared to what some parts of the business have seen before, and we must speak clearly about why we’re doing that and why we think it’s essential.

Consequently, we planned to do the road test, collect some wins, and earn some scars, informing us for when it comes time to scale up. Starting small is the best way to make these changes stick. The alternative is asking for all the teams upfront, having to hire 10+ teams while you’re trying to build a brand new way of working together. Organised Chaos would be a gentle description, and in doing this, we would be failing the business in what we promised. We’d be acting big and thinking small when really we want to think big and act small. We want iterative, not big bang.

Boyd Multerer, Xbox’s father of innovation, once told me this: Think very carefully about who the first member of the team is. Who are the founding members? You only get to make your culture once. It’s those people who will set it, and after those founders set it, it’ll be tough to change that culture.

I’m incredibly proud of the first team. The team is a mixture of internal and external hires, with a broad technical base and deep knowledge of the technology stack and our domain. We have a culture of writing, of collaboration first, and of always delivering incremental value. Boyd’s words ring true.

With the team in place, the time comes to loudly and explicitly make space for experimentation. There is so much discovery to do for a new team to move from forming to performing while figuring out the domain, the architecture, the strategy and everything else they’ll need to think big and act small. You might consider that first team to be the groundbreakers, but every new team you hire that looks and works that same way will need to make discoveries of their own.

All of the value streams that run through your business will be different, and those teams will need to engage and model themselves differently. What are the engagement modes, and what team topology will each stream require? How will we hire and onboard supporting teams? How will we draw the wider org into the conversation?

Most challenging of all, how will we build community? How will we move from being a bunch of people who don’t know each other well to be many people who have strong community links across the organisation? Those relationships will see those teams through hard times; building community is a top priority.

Every team will be different, that’s okay.

We’re rolling out right now so a lot of this is planned-but-not-actual, or actual-but-only-since-Tuesday so forgive me that. These lessons are hot off the press and our journey is incomplete, I hope to perpetually remain with that feeling of incompleteness at the same time as I watch us grow, deliver, reshape and grow again.

Conclusions

Wrapping up, I have some closing thoughts:

• Team Topologies can work well, and when you’re potentially throwing the whole org into upheaval, you better have done the homework.
• Communicating well and getting the logistics right are the two single most significant determinants in delivering. Invest the time and energy to get those things right.
• Your top-level streams of value are important; if you can identify those initial streams accurately, you’ll have an easier time figuring out how to split them when the time comes.
• Humans are social creatures. Get buy-in. Get help. You can’t do it on your own.
• We’re rolling out more teams and more streams faster than we thought we would. The ultimate mark of success in my book is more teams delivering more value to customers.

Citations and Further Reading

• Conway, Melvin E — How do committees invent?
• Skelton, Pais — Team Topologies
• Skelton, Pais — DevOps Topologies
• Wikipedia, Conway's Law
• Applying Conway's Law to improve your software development
• Wikipedia, Cognitive Load
• Wikipedia, Humanism
• Steve Blank — Harvard Business Review, McKinsey's Three Horizons Model Defined Innovation for Years. Here's Why It No Longer Applies
• McKinsey and Company, The Three Horizons of Growth
• News, Microsoft — Boyd Multerer

Environment:

Things move quickly in the JS ecosystem. Here are the library versions used in the subject API at the time of writing:

"dependencies": {
    "@types/express": "~4.0.39",
    "@types/sequelize": "^4.27.21",
    "express": "~4.16.2",
    "sequelize": "4.38.0",
  }

Context:

I have an identifier in one system that I need to correlate with an identifier in a second system, but I could only do that via an intermediate identifier, also in the second system. A good case for a SQL Join.

In System 1, I have enough information to send this request:

{
    "items": [
        "ABC",
        "DEF",
        "GHI"
    ]
}

And in response I want:

{
    "links": [
        {
            "rel": "self",
            "href": "https://api.com/123-i-am-a-uuid"
        }
    ],
    "reference": "123-i-am-a-uuid",
    "items": [
        {
            "legacyId": 123,
            "electronicId": "ABC"
        },
        {
            "legacyId": 456,
            "electronicId": "DEF"
        },
        {
            "legacyId": 789,
            "electronicId": "GHI"
        }
    ]
}

The initial approach was to make three repository queries to get the data I needed, and then go through three javascript map operations to splice the data into the above format. Using a series of javascript maps is inefficient, particularly as the data set grows.

A better way is to get SQL to do the grunt work, as it’s far more time and memory efficient than the javascript I would have needed to write.

As an aside, I’m not too fond of Javascript on the back end. I don’t feel it’s performant enough and as your codebase grows the lack of a robust type system hurts more and more. Typescript helps address the latter (assuming your libraries support it) but does nothing for the former. A typed language like C# or Java is preferable for web programming in a large enterprise due to better performance, more coherent ecosystem (see: left-pad) and robust type system.

I need to make a map of identifiers from an electronicIdEvent entity (that deals with electronic identifiers) and an animal entity that deals with animal information.

I need the legacyAnimalId field. To find a legacyAnimalId given an electronicIdEvent, I have to:

1. Find all electronicIdEvent rows that match an electronicId.
2. Find all animal rows that match the animalId of the electronicIdEvent where an electronicId is present.
3. Return all legacyAnimalId rows that match the animalId of both the animal and the electronicIdEvent.

Hopefully, you can see why using javascript maps, and SQL selects for this would be tedious and inefficient.

Here’s a SQL query that demonstrates what I want if you’re more familiar with SQL then Javascript:

select event.eid, event.animalId, animal.id, animal.animalKey
from "electronicIdEvent" event
    inner join "animal" animal
on event."animalId" = animal.id

1. Create associations for Sequzelize, between the data you need to link.

For Sequelize to generate the right SQL, it needs to know about the relationships between your data.

Here’s the code that creates associations in Sequelize:

this.animal.hasMany(this.electronicIdEvent, {
  foreignKeyConstraint: true,
  foreignKey: "animalId",
});
this.electronicIdEvent.belongsTo(this.animal, {
  foreignKeyConstraint: true,
  foreignKey: "animalId",
});

Associations allow the ORM to understand your relations and map One To One, One To Many and Many To Many relationships to appropriate SQL code. The docs describe this here

2. Create a Sequelize repository method that uses this association to form a SQL query that returns the correct data:

There is some stuff in here that’s not great, but it works well enough. If I had more time, I’d figure out a way of using typescript’s not-null override (!), and ideally find a way of making event a typed response.

The pseudocode I want is:

• First return all the rows for the electronicId and animalId columns in electronicIdEvent, where the electronicId is present in my electronicIdList
• Next join the rows for those columns with the rows for the legacyAnimalId column, where the animalId is the same in both the electronicIdEvent and animal entities.
• When the data comes back, drop the animalId column. I don’t need it once it has done the job of being the glue between the other entities and columns.

Or, as Javascript:

// imports omitted for brevity

export class AnimalRepository {
  constructor(
    private db: AnimalTimelineDbContext,
  ) {}

getLegacyAnimalIdentifierByElectronicIdentifier(electronicIdList: Array<string>): Promise<Array<IdentifierMap>> {
    return this.db.electronicIdEvent
      .findAll({
        attributes: ["electronicId", "animalId"],
        where: {
          electronicId: electronicIdList,
        },
        include: [ 
          {
            model: this.db.animal,
            required: true,
            attributes: ["legacyAnimalId"],
          },
        ],
      })
      .then((events) =>
        events.map((event) => ({
          eid: event.electronicId,
          legacyAnimalId: event.Animal!.legacyAnimalId,
        }))
      );
  }
}

Note: Setting required: true in the include block forces the query to only return records which have an associated model, this converts the query from an OUTER JOIN to an INNER JOIN.

Because we only return complete rows (no partials) event.Animal cannot be null, I can override the typescript hint, i.e. event.Animal!.legacyAnimalId.

I’m done at this point. We’ve submitted a list of electronic identifiers and gotten back an Array<IdentifierMap>, which is syntactic sugar for Array<[string, integer]>.

3. Convert the raw data into my map object, and fire the response back.

Because Sequelize is doing most of the grunt work in formatting the data, all I need in my web layer is to add the UUID that the user-submitted and save that map. Once I’ve saved the map and returned the reference to the calling system, the calling system can ask for that map and get the data (this is the most RESTful way of handling the data exchange and I’m omitting that setup for a follow-up post).

In it, I talk about the basics of Actions, how they work, what the language looks like and how you can get started. If you’ve never used Actions before, I highly recommend you have a quick read of that before reading this, as I build on some of the ideas presented there.

Continuous Integration (CI) versus Continues Deployment (CD) versus Continuous Delivery (unhelpfully, also CD)

Put simply, continuous integration is the act of continually moving your changeset into the wider codebase, as frequently as it makes sense for your use case. CI is an essential practice because it drives us as engineers to produce smaller changes more often, and these small changes tend to be less risky individually. Those small changes also lead us to deliver value to our users more rapidly, and more often.

Continuous deployment is the engineering decision to ship validated or verified changes to production environments as often as practical. The decision to continually deploy tends to be made for the same reasons as we choose to continuously integrate. It’s about reducing risk, making improvements available sooner, and building trust with users and with our less technology-focused colleagues.

The natural extension of continuous deployment is continuous delivery. While continuous delivery has become an umbrella term to describe all of the bits and pieces that contribute to it, I do see these things as separate concepts. The key difference then is that continuous deployment is an engineering decision to ship code to production. Continuous delivery is the product or broader business decision to make the features that our code provides, available to users.

Each concept requires the predecessor to work, but it can be a valid choice to stop at any of these points and not continue on. My own bias is to adopt continuous delivery as a fundamental practice, but your own operating context will have impacts on what parts of this you can and can’t do.

Continuous Delivery is a foundational skill that your organisation needs to be good at if it is to remain responsive and ’lowercase a’ agile.

In the previous article, I stated:

More concretely, a decent CI/CD solution will:

• Build your code
• Run the tests
• Deploy it to an environment
• Roll-back if there is an issue

My initial implementation of Github Actions saw me using the tool primarily for continuous integration. However, I’ve recently expanded that to include continuous deployment (and since I’m not using feature flags yet, this technically qualifies as continuous delivery if only as a side effect).

Github Actions now owns artefact build across all environments.

Previously, my create-rc.yml workflow built a container in dev, tested that and then told Heroku that the build is good, and to cut a release.

Heroku then would pull the code, build it and release it to my dev environment. I wasn’t actually running the code I tested, I was running code built from the code I tested. This has been the source of subtle but pernicious bugs for me in the past. My rule of thumb is that you want to build your release candidate once and pass it through environments. That way you know for sure, and can prove in an auditable way, that this particular code is running in this specific place.

Note: The Heroku CLI is bundled as standard on Github Actions runners. I couldn’t find this documented anywhere and literally only stumbled on it in a fit of frustration at midnight last night. My new heuristic is that if you need a specific tool, assume it’s on the runner but isn’t necessarily up to date. If your dependency isn’t there, then you should try to work around it.

I assumed that Heroku CLI wouldn’t be there and spent a long time trying to fight shadows. Don’t be like me.

Here’s a high-level summary of the work I did to make my builds work the way I’ve described above, with one RC being deployed to many environments:

1. Have create-rc.yml treat the docker image it makes like the one RC, rather than as a means of delivering integration tests.
2. Improve the tagging process so that we produce a docker image with the right naming conventions for Heroku.
3. Push the image to the Heroku docker registry, where we can persist it across builds and environments.
4. Introduce a new job to deploy the verified image to the right Heroku environment.
5. Introduce a new workflow with a different trigger, to take the already validated image and redeploy it to production.

Overall the changes weren’t massive, but I definitely cut myself on some rough edges (documentation being a big part of that).

These steps build my image, tag it and send it off to Heroku. That’s step 1, 2 and 3 done in ~20 lines:

- name: Login to Heroku Registry
  env:
    HEROKU_API_KEY: ${{ secrets.HEROKU_TOKEN }}
  run: heroku container:login

- name: Build and push
  env:
    HEROKU_API_KEY: ${{ secrets.HEROKU_TOKEN }}
  run: heroku container:push -a dev-api-spring-boot web

- name: Create tarball from docker image
  # Heroku has a naming convention for images, it's important to match that.
  run: docker save registry.heroku.com/dev-api-spring-boot/web > spring-boot-api-candidate.tar

- name: Upload image tarball for next job
  uses: actions/upload-artifact@v2
  with:
    name: spring-boot-api-candidate.tar
    path: spring-boot-api-candidate.tar

These steps close out the only actual building of code that I do. In every other case, I get code from one place to the other by redeploying code I already know to be good. It’s important to note here that I’m trying to keep build time low by using capabilities baked into the actions runner, rather than using externally published actions.

It’s also important to note that if you use Heroku commands the way I am, you lose visibility of fine-grained build actions because most of that code lives in your docker file. By that, I mean that all I can see in this code is that Heroku is pushing a container. I can’t see how it’s built. For that, I need to go to my Dockerfile, which in this case looks like this:

FROM gradle:6.5.1-jdk14 as build-stage

WORKDIR /build
COPY src /build/src
COPY gradlew /build/gradlew
COPY gradle /build/gradle
COPY build.gradle /build/build.gradle
COPY settings.gradle /build/settings.gradle

RUN /build/gradlew clean build -x test

# Running container build begins
FROM adoptopenjdk:14.0.1_7-jre-openj9-0.20.0-bionic

# copy application JAR
COPY --from=build-stage build/build/libs/spring-boot-api-*.jar /spring-boot-api.jar

# specify default command
# The command to run this in local mode would be docker run -p 8080:8080 -e JAVA_OPTS="-Dspring.profiles.active=local -Dserver.port=$PORT" registry.heroku.com/dev-api-spring-boot/web
CMD ["sh", "-c", " java ${JAVA_OPTS} -jar /spring-boot-api.jar"]

Now I have two sets of build logic in two places, which isn’t perfect, but given how docker works, it’s tolerable. An example of the impact this has is that if I want to stop running tests while I build the image (because I unit test and integration test within the workflow), I need to add -x test to the end of my Gradle command in the Dockerfile as seen here. It adds a little bit of cognitive burden. Okay for now but not ideal.

Speaking of unit tests, since I want to cut down my build time, I can run them in parralel! Hooray for Github’s jobs are parralel by default stance!

unit-test:
  runs-on: ubuntu-latest
  needs: build-image # build-image is the name of the first job in this workflow, it's where the Heroku code above lives.

  steps:
    - name: Check out code
      uses: actions/checkout@v2

    - name: Set up JDK 14
      uses: actions/setup-java@v1
      with:
        java-version: 14

    - name: Make gradle wrapper executable
      run: chmod +x gradlew

    - name: Run Unit Tests
      env:
        PORT: 8080
      run: ./gradlew clean test

Releasing a verified image to Heroku

The great thing is that we only need to add one more step to our create-rc.yml (although this file should probably be renamed to dev-build or something simillar). What I’m saying below is that at the end of my build, only when I’ve got green unit tests and green integration tests, I want that image that I’ve already pushed, to be activated in Heroku.

dev-deploy:
  runs-on: ubuntu-latest
  needs: [integration-test, unit-test]

  steps:
    - name: Login to Heroku Registry
      env:
        HEROKU_API_KEY: ${{ secrets.HEROKU_TOKEN }}
      run: heroku container:login

    - name: Release to Heroku dev
      env:
        HEROKU_API_KEY: ${{ secrets.HEROKU_TOKEN }}
      run: heroku container:release -a dev-api-spring-boot web

I don’t have to care about artefact handling or pass in a tarball. The image is always current, and I just choose whether or not I want to make it active. One of the drawbacks here though is that I could get an image pushed that fails unit tests or integration tests. This is mitigated by the image remaining inactive until I release it. There is an edge case here that if I had to rollback, I might roll back to a bad image but that’s a problem for improvement later - and I’ll never have a broken image that won’t start because if the image won’t build, the build job will fail.

So with the above changes, we have a dev build process entirely owned by Github Actions. In theory, I could rip out Heroku and point to AWS ECS or somewhere else quickly. I’m using my platform provider for its platform, not for the stepladder on to the platform!

Releasing to Production with Sentry Integration

My procedure is that a release to production is triggered on a push to main, and the only way to push to main is via a merged commit. This procedure needs to do a few things:

1. Take a validated image from an upstream environment and retag it.
2. Push that retagged image back to Heroku
3. Release the image
4. Create a new release version in Sentry

I have some intermediate steps here that I want to use to tie things together from an audit perspective, but I’m waiting on some feedback from elsewhere before I can do that. Here are the steps for my release job, note how similar it is to my dev release methodology.

- name: Login to Heroku Registry
  env:
    HEROKU_API_KEY: ${{ secrets.HEROKU_TOKEN }}
  run: heroku container:login

- name: Pull dev image
  run: docker pull registry.heroku.com/dev-api-spring-boot/web

- name: Re-tag dev as prod
  # Again, Heroku expects a naming convention here, so we just have to comply.
  run: docker tag registry.heroku.com/dev-api-spring-boot/web registry.heroku.com/api-spring-boot/web

- name: Push production image
  run: docker push registry.heroku.com/api-spring-boot/web

- name: Push Prod Image
  env:
    HEROKU_API_KEY: ${{ secrets.HEROKU_TOKEN }}
  run: heroku container:release -a api-spring-boot web

The post-processing I do on a release is much more interesting then docker jiggery-pokery:

1. I want to grab the entire codebase because I want that delicious commit history.
2. I want to create a new tag for this production release
3. I want to get all of the commit descriptions between the new tag, and the previous tag, and then filter out some commits that aren’t interesting for given values of interesting
4. Then cut a release for Github using the commits as a changelog
5. Finally, use Sentry.io for crash reports, and I want to tell Sentry about the new version so that I can track where issues might have been introduced.

- name: Checkout code
  uses: actions/checkout@v2
  with:
    # Fetch depth grabs the entire history, though I'm sure I could grab the commits since the last tag if I really wanted.
    fetch-depth: 0

# I encountered an issue here so have left this commented out. It's not a part of my workflow, but hopefully one day it'll create tags for me
# Leaving this out for now - to use the output of tag in the below release use ${{ steps.create_tag.outputs.new_tag }}
#      - name: Bump version and push tag
#        id: create_tag
#        uses: mathieudutour/github-tag-action@v4.5
#        with:
#          github_token: ${{ secrets.GITHUB_TOKEN }}
#          release_branches: dev

- name: Generate release notes
  # Important note: I use https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit for commit format. It makes it really easy to filter commits in the way I've done below.
  run: git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%s" -i -E --grep="^(build|ci|docs|feat|fix|perf|refactor|style|test)*feat|perf|fix" > release-notes.txt

# I don't want to cut releases with no info in them! That's why this too is not currently part of my workflow
#      - name: Create Github Release
#        id: create_release
#        uses: actions/create-release@v1
#        env:
#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
#        with:
#          tag_name: ${{ github.sha }}
#          release_name: Release ${{ github.sha }}
#          body_path: release-notes.txt
#          draft: false
#          prerelease: false

- name: Create Sentry release
  uses: tclindner/sentry-releases-action@v1.2.0
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_ORG: my-sentry-org
    SENTRY_PROJECT: spring-boot-api
  with:
    tagName: ${{ github.sha }}
    environment: heroku-prod

The net effect of the above is that I get to take a previously validated image. When I choose (via merged PR), I can automatically redeploy quality code to prod without rebuilding. The neat interplay here is that when I open that PR, my project will build, and use that same build to decide whether or not I can merge. As soon as I merge, the code is in prod without a rebuild. It’s nice.

With a new release being cut in Sentry each time, I can resolve errors that I’ve introduced down to at worst, a PR or at best, an individual commit. Also nice!

A full solution for continuous delivery tends to include (but isn’t limited to):

• The ability to create artefacts that we can release to production, across many products, teams, branches, environments and repositories.
• The ability to quickly validate an artefact as a candidate for release (through applying the testing triangle - unit, integration, acceptance, smoke and so on).
• The ability to release code to production without necessarily activating it for users (typically through feature flags, canary built and graduated rollouts).
• The ability to rapidly respond if a release candidate we later find to be problematic (again through canary builds, graduated rollouts, and by quickly rolling back software found to be problematic).
• The ability to audit or understand what code is where, what state that code is in, and why that code is where it is.

More concretely, a decent CI/CD solution will:

• Build your code
• Run the tests
• Deploy it to an environment
• Roll-back if there is an issue

Building an excellent build tool is no easy task, and because of the variety of use cases out there, you tend to find tools optimised for those use cases. They’ll be passable or useful in that niche and poor outside of it. Use-case variety and the complexity of the problem space is part of the reason why container-based builds have taken off. Where previously I’d have precious build agent boxes sitting somewhere that I’d need to feed and water and love and sell my children to, now I can have a dumb build box that knows about nothing. The build box just grabs a container off the internet (or I make a custom container) to fill my needs.

Github Actions

Github Actions is one such container based build offering, though at first they don’t tell you that!

The highest order concept in Actions is the Workflow. A workflow consists of several jobs, and each job can have several steps. Here’s an example we’ll become a bit more familiar with later:

As you can see, A workflow, is a set of jobs (that we run in series or parallel), with each job containing several steps. Jobs describe collections of steps that when together, perform some action that is useful to the business. Model your jobs in terms of things that are useful for you - it’s these aggregates that you’ll be watching most.

Steps are concrete actions that we perform, things like building, unit testing, renaming files and so on. A step is the smallest unit of work you can do in a workflow, and they don’t need to be useful in and of themselves.

The reason I think that jobs should be useful units of work for your business, is because if you plan them that way, it becomes trivial to re-use jobs to achieve new functionality quickly

Pipelines as Code with… YAML

Workflows use YAML as the format of choice, and I YAML in Github Actions as much as I hate any other white spaced language in a place it doesn’t belong. I’m sure Github chose YAML for a good reason, I’ve struggled to find out what those reasons were or are. Work continues in that area.

As with most things that involve YAML, the workflow file is easy to quickly grok while it’s small to medium length but challenging to troubleshoot or do anything with once it gets a bit bigger. Github Actions is still new, so I can understand why it might be a little rough around the edges. Perhaps there is tooling around the workflow file I’m ignorant of, but an equivalent to Bitbucket Pipelines’s pipeline validator would be an excellent addition.

Even better still (and this would be a feature far down the track), give me a fluent API akin to Bamboo's Java Spec Concept .

To save you a click, 90% of my warm fuzzies for Atlassian Bamboo come from being able to do this:

private Plan createPlan() {
    return new Plan(
            project(),
            "Plan Name", "PLANKEY")
            .description("Plan created from (enter repository url of your plan)")
            .stages(
                    new Stage("Stage 1")
                            .jobs(new Job("Build & run", "RUN")
                                    .tasks(
                                            new ScriptTask().inlineBody("echo Hello world!"))));
}

Getting access to this kind of API, and provide auto-completion, intellisense and everything that comes with that ecosystem is war-winning feature for pipeline builders.

I would prefer XML to YAML. There. I said it. We can move on now.

Workflows

What does a workflow file look like? Here’s the file for a Spring Boot application I’m currently working on. I was very focused on getting a minimal workflow up and running, so there are things to be added and things to be optimised.

Have a big read, and I’ll break it down below:

name: Create Release Candidate

on:
  push:
    branches: [ dev ]
  pull_request:
    branches: [ dev ]

jobs:
  create-rc:
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v2

      - name: Build and tag release candidate
        uses: docker/build-push-action@v1.1.0
        with:
          username: ${{ secrets.HEROKU_USER }}
          password: ${{ secrets.HEROKU_TOKEN }}
          registry: registry.heroku.com
          repository: image-repository/heroku-process
          tags: latest
          push: false

      - name: Create tarball from docker image
        run: docker save registry.heroku.com/image-repository/heroku-process:latest > heroku-process-candidate.tar

      - name: Upload image tarball for next job
        uses: actions/upload-artifact@v2
        with:
          name: heroku-process-candidate.tar
          path: heroku-process-candidate.tar

  integration-test:
    runs-on: ubuntu-latest
    needs: create-rc

    steps:
      - name: Check out code
        uses: actions/checkout@v2

      - name: Download tarball
        uses: actions/download-artifact@v2
        with:
          name: heroku-process-candidate.tar

      - name: Load image from tarball
        run: docker load < heroku-process-candidate.tar

      # github doesn't allow us to gracefully expire artifacts (e.g. keep last 10 build artifacts and no more)
      # if we don't delete these, we'll hit the storage limit for actions quickly.
      # persisting docker images outside of builds should be done by pushing the image to a registry
      # we should rm the tarball as soon as we've loaded it as a docker image.
      - name: Tidy up artifact to avoid storage limit
        uses: geekyeggo/delete-artifact@v1
        with:
          name: heroku-process-candidate.tar

      - name: Run application server
        run: docker run -d -p 8080:8080 -e JAVA_OPTS=-Dspring.profiles.active=dev registry.heroku.com/image-repository/heroku-process:latest

      - name: Make server watch script executable
        run: chmod +x wait-for-heroku-process.sh

      - name: Wait for server to start
        run: ./wait-for-heroku-process.sh

      - name: Set up JDK 14
        uses: actions/setup-java@v1
        with:
          java-version: 14

      - name: Make gradle wrapper executable
        run: chmod +x gradlew

      - name: Run Integration Tests
        run: ./gradlew integrationTest

The above file is just under 100 lines of YAML to describe the first two jobs in the image above (Package for release and Run Integration tests). Now that I’ve finalised everything, it looks pretty clean and tidy, the process to get there was anything but. Again this is something that I’d attribute to new-ness. Still, Github Actions does an excellent job at giving you the low-level details about how a thing works, but a lousy job at describing how you can use what Actions provides you to create higher-order pipelines.

For example, the Gradle starter here does a good job of telling me how to declare jobs, steps and make them dependent on pull requests or branches. It also leaves me with questions. I want to package my application, and then run it, and then only when it’s running, run unit tests. How do I do that? I want to publish to my registry, but only if the unit and integration tests have passed, except for in dev, we can publish there with some failing tests. How do I do that?

The basic building blocks are there, but more complex pipeline logic is missing.

Compare this with the excellent documentation produced by VMWare and Pivotal for Concourse CI that gets much more into higher-order combinations of those basic building blocks.

Compare Gated CI Pipelines and Blue-Green Deployments with Concourse, to anything in the only workflow template repository I could find, Starter Workflows to see that high level / low-level split.

Concourse is a more mature product and more fully-featured, where perhaps Github Actions is still more of a CI tool rather than a CD tool. I’m sure it will get there in time. The portability and reusability that Github Actions provides is a significant advantage over other build tools.

I love how sturdy the modelling and pipelining features are for Concourse. It’s ironic though that at my current workplace we’ve just decided to get off Concourse CI in favour of Github Actions.

Jobs in detail

Here’s the same workflow as above, trimmed for easier reading.

name: Create Release Candidate

on:
  push:
    branches: [ dev ]
  pull_request:
    branches: [ dev ]

jobs:
  create-rc:
    runs-on: ubuntu-latest

    steps:
      - name: Arbitrary Step 1
        run: echo "Hello Muddah"

      - name: Arbitrary Step 2
        run: echo "Hello Fadduh"

  integration-test:
    runs-on: ubuntu-latest
    needs: create-rc

    steps:
      - name: Arbitrary Step 1
        run: echo "Here I am at"

      - name: Arbitrary Step 2
        run: echo "Camp Granada."

Important Concepts: Jobs and Steps

• A workflow has one set of jobs
• A job has one set of steps.
• Both of these sets can have one to many items in them. You can have ten jobs, each with 20 steps, or one job with 1 step.
• To create a sequential pipeline, add a needs statement in every job after the first one, and in that needs statement, refer to the previous job. For example, I have two jobs, create-rc and integration-test. In the second job, I have this statement: needs: create-rc.
• Importantly, Jobs run in parallel by default. A sequential run like the above is something you have to do specifically. Parallel by default creates advantages if you can decouple your build process.
• Right now, I have to wait for Actions to build my RC and image before I can integration test. I believe in pushing one artefact through the entire pipeline rather than rebuilding it each from source each time - but if I didn’t, I might be able to get super parallelisation on my build pipelines. I.e. rather than Checkout Source > Build > Test > Deploy with one artefact the whole way through, I could Checkout Source > Build, Checkout Source > Test, Checkout Source > Package > Deploy all at the same time. This means the time the build takes is the max() of the longest job, rather than sum(job_1 + job_2 ... job_n).
• I’m an absolute savage though and believe that the best approach is to checkout and built once, and then pass an artefact all the way through. The tradeoff for that certainty is a longer build time (about 5 minutes in this case, but for longer build processes, it probably stacks up quick).
• There is a whole ecosystem of Actions available on the Github Marketplace, but every action you use will cost you in build time. Actions are distributed as Docker images, and when your build runs, before you can build your build, you have to build all of your actions.
• Steps all run sequentially, and an action can be a step, but not all steps have to be actions. For example:

- name: Arbitrary Step 1
  run: echo "Hello Mother"

The above is a step that is not an action; the below is a step that is action. All actions are steps, but a step does not have to be an action.

- name: Build and tag release candidate
        uses: docker/build-push-action@v1.1.0
        with:
          username: ${{ secrets.HEROKU_USER }}
          password: ${{ secrets.HEROKU_TOKEN }}
          registry: registry.heroku.com
          repository: image-repository/heroku-process
          tags: latest
          push: false

Sharing and Storing Artifacts

Each job runs in parallel and runs in a separate container. If you have a job that builds, and you have a job that tests, you have to figure out a way to get the build output into the testing task. Github’s solution to this seems inefficient, but I can’t see any better way of doing it.

Your workflow could happen anywhere, multiple anywhere even. Because jobs are independent, in theory, you could have your build happening over in the US East region and your tests happening in Europe. You can’t rely on them being on the same machine or even in the same DC, so sharing artefacts via cloud storage is the only choice you have.

It gives rise to these two actions:

- name: Upload image tarball for next job
        uses: actions/upload-artifact@v2
        with:
          name: heroku-process-candidate.tar
          path: heroku-process-candidate.tar

- name: Download tarball
        uses: actions/download-artifact@v2
        with:
          name: heroku-process-candidate.tar

      - name: Load image from tarball
        run: docker load < heroku-process-candidate.tar

The way we share artefacts between jobs (or persist them outside of builds) is essentially by uploading and downloading from S3 or an equivalent (I assume they use S3 but haven’t done the research to confirm). I have a small workflow right now, but what this means is that passing my artefact from my first job to the second, accounts for a whopping 21% of the run time of the build. This behaviour pushes me to a perverse outcome where I’m better off starting from scratch in every single job because of the time it takes to trade artefacts! An alternative to that would be to have one enormous job, but that also flies in the face of the whole idea of Github Actions, which is that concept of composable, reusable workflows.

Further, you need to be careful with your usage of artefacts.

On a team or pro plan, you get 2GB of storage for actions. Artefacts associated with builds older than 90 days get deleted. To naturally stay at or under the 2GB limit, your builds need to persist fewer than 22MB per day - not per build, per day worth of artefacts. Github Packages, and storage for Actions, get very spendy, very quickly.

This behaviour gives rise to actions like this one. I consider this 100% required for anybody who has Workflows with more than one job, where you need to pass an artefact between them. Remember, every job that needs to share an artefact will incur the wrath of Github Packages.

      # github doesn't allow us to gracefully expire artifacts (e.g. keep last 10 build artifacts and no more)
      # if we don't delete these, we'll hit the storage limit for actions quickly.
      # persisting docker images outside of builds should be done by pushing the image to a registry
      # we should rm the tarball as soon as we've loaded it as a docker image.
      - name: Tidy up artifact to avoid storage limit
        uses: geekyeggo/delete-artifact@v1
        with:
          name: heroku-process-candidate.tar

As per the comment, I’d recommend you persist artefacts during builds and between jobs, delete them afterwards, and for audit, viewing test reports and things like that, find somewhere else to put them. Put containers into your registry, put test reports into S3 or similar. For more detail on how this all gets billed, see this

In closing, why use Actions?

I think for a lot of people (myself included), the main draw for Github Actions is that it’s conceptually quite simple (though as with anything there are gotchas), and tightly woven in with Github itself. I like that the build lives close to the code and everything that comes with it. Github Actions is ‘pipeline-as-code’, that isn’t that much of a burden to learn and use, and even having been newly released, it’s as capable as any other build tool I’ve used.

Where it starts to get powerful is the open-source ecosystem of Actions and the tie into wider Github. Be that the code repository or other apps I might have added to my repo or org. I can get this without having to deal with another tool, another login, or the overhead of another new thing. Thinking on it, maybe that’s why they chose YAML.

While I’ve spent a lot of time bagging it, I quite like it. It’s a good example of delivering just enough capability at the right time, and I’m sure Actions will continue to grow, if not via first-party development, certainly through that action ecosystem.

Yes, I’ve got gripes about YAML, but I have that most places I go. You can work around the storage issues, and it’s not unreasonable for Github to try and make money given everything else they provide for free or for cheap. Actions is a fully managed service, no servers to feed and water, no breaking updates so far. With versionable pipelines, there are very few moving parts that we the end-users have to care about. That’s worth more than it’s equivalent weight in gold.

If you’ve got a pet project or something new at work, I recommend you give it a try.

The Spring Ecosystem

When you need to create a web application or an API in Java, be that RESTful, SOAP or GraphQL; whether you’re looking at synchronous HTTP, Asynchronous or Reactive, Messages on Queues or Event Sourced with Kafka, it’s hard to go past the Spring Ecosystem. If nobody ever got fired for buying IBM, you could probably say that nobody ever got fired for creating a Spring-based application.

Spring is an extremely popular, well maintained and well known Java Web Application Framework. Spring Boot makes it easy to create stand-alone, production-grade Spring based Applications that you can “just run”.

Spring Boot is to Spring and Java as Ruby on Rails is to Ruby. So if you’re working in a Java environment, there’s a pretty good chance you’re using Spring or Spring Boot. Even if you’re using another framework, it’s worth learning about these - they’re so ubiquitous they’ll be around for a long time!

Database Migrations

If you’re using Spring, there’s a chance you’re using persistence tech like Hibernate , Jooq or Ebean to get data out of your database.

Features come and go; data models change; what happens when you need to change your data model? You run a database migration to add or remove columns or make other changes.

It used to be that this would happen manually; someone would log on to a database, run a bunch of SQL and rely on the fact that you’ve made the same changes in your application. There is a bunch of room for human error here, though. So we improve on this by trying to make our database changes safer. Version control, repeatability, and testability become applicable to more parts of the stack. Databases included.

Both Liquibase and Flyway help us with these migrations. Spring helps us with Liquibase and Flyway in turn. The result is a database changeset that does what we have specified every single time (of course, we might still specify the wrong thing - computers remain computers). All we need to do is write a migration and dump it into a folder in our Spring project to achieve that result. Spring handles the rest.

Liquibase

Liquibase is offered free and paid. They don’t share pricing on their website, though, which makes me suspicious. They don’t do an excellent job of describing why I would want to pay either. Liquibase offers migrations both through XML and SQL. The basic concept is that you have a master file that describes your database configuration and the changesets you want to include in your run. Spring comes in at that point, parses your config and your included changesets, and manages them appropriately.

Flyway

Flyway is offered free and paid, the same as liquibase. The pricing and feature breakdown is available here - and is a lot more detailed than anything I could find on liquibase.

Flyway focuses on your migrations as a first-class concept. You write SQL scripts, place them in a folder in your Spring project, add some config to your application.yml files and then Spring runs the migrations as per your config.

Links:

• Spring Boot
• Liquibase
  • Using Liquibase with Spring Boot
• Flyway
  • Using Flyway with Spring Boot

Using Liquibase

Note: I’m using Spring Boot 2.2.6 with Gradle here, but you can do the equivalent with a dependency block in Maven.

Step One is adding your dependencies to build.gradle:

    // Persistence
    implementation('com.h2database:h2')
    implementation "org.liquibase:liquibase-core"
    liquibaseRuntime "org.liquibase:liquibase-core"
    liquibaseRuntime sourceSets.main.compileClasspath
    liquibaseRuntime "org.postgresql:postgresql"
    liquibaseRuntime "com.h2database:h2"
    implementation('org.postgresql:postgresql')
    implementation('org.springframework.boot:spring-boot-starter-jdbc')

Next we need to make new folders in our project:

• In src/main/resources add a liquibase folder
• Add two subfolders, changelog and fake-data

Add some minimal configuration to your application.yml file and you’re good to go.

  liquibase:
    contexts: dev, faker
    change-log: classpath:liquibase/master.xml

At this point, you should be able to start writing some XML.

You’ll need a master.xml that describes your environment setup and the migrations that you want to run. Here’s an example:

<?xml version="1.0" encoding="utf-8"?>
<databaseChangeLog
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.6.xsd">

    <property name="now" value="now()" dbms="h2"/>
    <property name="now" value="current_timestamp" dbms="postgresql"/>

    <property name="floatType" value="float4" dbms="postgresql, h2"/>
    <property name="clobType" value="longvarchar" dbms="h2"/>
    <property name="clobType" value="clob" dbms="postgresql"/>
    <property name="uuidType" value="uuid" dbms="h2, postgresql"/>

    <changeSet id="00000000000000" author="alex">
        <createSequence sequenceName="sequence_generator" startValue="1050" incrementBy="1"/>
    </changeSet>

    <include file="liquibase/changelog/20191024203226_added_entity_Company.xml" relativeToChangelogFile="false"/>
    <include file="liquibase/changelog/20191024203227_added_entity_Team.xml" relativeToChangelogFile="false"/>
    <include file="liquibase/changelog/20191024203234_added_entity_Project.xml" relativeToChangelogFile="false"/>
</databaseChangeLog>

It looks a bit busy but let’s break it down. First, we need to tell Liquibase about our database setup, and what values it should use for various data types:

    <property name="now" value="now()" dbms="h2"/>
    <property name="now" value="current_timestamp" dbms="postgresql"/>

    <property name="floatType" value="float4" dbms="postgresql, h2"/>
    <property name="clobType" value="longvarchar" dbms="h2"/>
    <property name="clobType" value="clob" dbms="postgresql"/>
    <property name="uuidType" value="uuid" dbms="h2, postgresql"/>

Next, we need to describe the changes we want Liquibase to make; in our case, we want Liquibase to create a sequence and run three migrations. Note that if you write migrations but don’t include them in master.xml, they won’t run.

    <changeSet id="00000000000000" author="alex">
        <createSequence sequenceName="sequence_generator" startValue="1050" incrementBy="1"/>
    </changeSet>

    <include file="liquibase/changelog/20191024203226_added_entity_Company.xml" relativeToChangelogFile="false"/>
    <include file="liquibase/changelog/20191024203227_added_entity_Team.xml" relativeToChangelogFile="false"/>
    <include file="liquibase/changelog/20191024203234_added_entity_Project.xml" relativeToChangelogFile="false"/>

Here’s the company migration:

<?xml version="1.0" encoding="utf-8"?>
<databaseChangeLog
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.6.xsd">

    <changeSet id="20191024203226-1" author="alex">
        <createTable tableName="company">
            <column name="id" type="bigint" autoIncrement="${autoIncrement}">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="name" type="varchar(255)">
                <constraints nullable="false"/>
            </column>
            <column name="web_page_address" type="varchar(255)">
                <constraints nullable="true"/>
            </column>
            <column name="billing_contact_email_address" type="varchar(255)">
                <constraints nullable="true"/>
            </column>
            <column name="primary_contact_email_address" type="varchar(255)">
                <constraints nullable="true"/>
            </column>

        </createTable>
    </changeSet>

    <changeSet id="20191024203226-1-data" author="alex" context="faker">
        <loadData
                file="liquibase/fake-data/company.csv"
                separator=";"
                tableName="company">
            <column name="id" type="numeric"/>
            <column name="name" type="string"/>
            <column name="web_page_address" type="string"/>
            <column name="billing_contact_email_address" type="string"/>
            <column name="primary_contact_email_address" type="string"/>
        </loadData>
    </changeSet>

</databaseChangeLog>

The first thing this migration creates is a table called Company. Since Liquibase uses XML as an abstraction on top of SQL, we don’t need to worry too much about compatibility, Liquibase will look at the XML file and translate our request to the appropriate SQL dialect.

    <changeSet id="20191024203226-1" author="alex">
        <createTable tableName="company">
            <column name="id" type="bigint" autoIncrement="${autoIncrement}">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="name" type="varchar(255)">
                <constraints nullable="false"/>
            </column>
            <column name="web_page_address" type="varchar(255)">
                <constraints nullable="true"/>
            </column>
            <column name="billing_contact_email_address" type="varchar(255)">
                <constraints nullable="true"/>
            </column>
            <column name="primary_contact_email_address" type="varchar(255)">
                <constraints nullable="true"/>
            </column>

        </createTable>
    </changeSet>

Having defined our table, we can take advantage of one of the neat functions Liquibase can give us - Liquibase will load data into our database from CSV:

    <changeSet id="20191024203226-1-data" author="alex" context="faker">
        <loadData
                file="liquibase/fake-data/company.csv"
                separator=";"
                tableName="company">
            <column name="id" type="numeric"/>
            <column name="name" type="string"/>
            <column name="web_page_address" type="string"/>
            <column name="billing_contact_email_address" type="string"/>
            <column name="primary_contact_email_address" type="string"/>
        </loadData>
    </changeSet>

The loading of data is a changeset in its own right; this means you can flexibly load data when you create the table, or at a later stage. Loading data in this way can be useful if you’ve got complex relationships to model. Another trick here is the context="faker" statement above. If you want data to be loaded, make sure your application.yml’s liquibase entry contains that tag. If you remove that tag, the data won’t be loaded.

Here’s the CSV referenced above with some sample data in it:

id,name,web_page_address,billing_contact_email_address,primary_contact_email_address
1,mobileFish,HomeLoanAccountTableComputer,Trace,SavingsAccountalarm
2,TastyMetalBacon,redChipsSoap,HomeLoanAccount,web-readiness

That’s it. When you run your spring boot application, during startup Liquibase will apply this migration, and when your app connects to the database, the tables and data will be ready immediately.

How does liquibase know the database credentials? I’m not sure! It’s magic. I assume it hooks into your spring database config, an example of which might be:

datasource:
    type: com.zaxxer.hikari.HikariDataSource
    url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
    username: sa
    password:
    hikari:
      poolName: Hikari
      auto-commit: false

Using Flyway

Flyway is a little bit different. The focus on SQL tidies things up, in my opinion.

First, you add the relevant dependencies:

// Persistence
    implementation('com.h2database:h2')
    implementation('org.postgresql:postgresql')
    implementation('org.springframework.boot:spring-boot-starter-jdbc')
    implementation "org.flywaydb:flyway-core"

Tell Flyway how to connect to your database (in my case, via application.yml):

  flyway:
    locations: classpath:db/migration/dev
    url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1
    user: sa
    password:

Make some folders, again in src/main/resources:

• Create db/migration
• In my case, I have H2 in dev and PostgreSQL in test and prod, so I have two sibling folders, dev and prod (test and prod scripts both live in prod as I want those to be the same, and they are the same SQL dialect).

The next step is to write some migrations in the appropriate SQL dialect. Where before our Company migration was in XML, now we’re in SQL, note that there is a naming convention here that allows us to cut down on boiler-plate. You have to name files like so V1.0__create_company.sql where the VX.x will define the order in which migrations are run. Anyway, here’s the file:

create sequence hibernate_sequence start with 1050;

create table company
(
    id                            uuid         not null,
    name                          varchar(255) not null,
    web_page_address              varchar(255),
    billing_contact_email_address varchar(255),
    primary_contact_email_address varchar(255),
    constraint pk_company
        primary key (id)
);

Dropping the XML leaves things a lot cleaner and readable, in my opinion. We load data as well, but this is just a SQL script rather than CSV:

INSERT INTO PUBLIC.COMPANY (ID, NAME, WEB_PAGE_ADDRESS, BILLING_CONTACT_EMAIL_ADDRESS, PRIMARY_CONTACT_EMAIL_ADDRESS)
VALUES ('1a689e52-f35b-4bda-934c-ea4f076bdc2c', 'Blue Fish Software Inc', 'bluefish.io', 'bills@bluefish.io',
        'hi@bluefish.io');

That’s it. When the application runs, it’ll load those SQL scripts and manage migrations and state for us. The disadvantage here is that we need two sets of scripts, one for H2 and one for PostgreSQL - this could be because my SQL is super weak and I can combine them but don’t realise it.

Comparing Liquibase and Flyway

I found Flyway to be a lot easier to use, despite having used Liquibase for a lot longer.

I like that Flyway is cleaner and less repetitive, and assuming I fix my dialect issue, it’ll be a case of 1000+ fewer lines of code with Flyway than with the same setup in Liquibase. I also found the docs Flyway provides to be a lot better, and I encountered far fewer undocumented tricks needed with Flyway. If crucial information needed to get going is easier to find on Stack Overflow than on your docs pages, you’ve done something wrong. Liquibase is bad for this.

Moving from bigint to uuid primary keys on all of my entities was impossible with Liquibase due to a bug around mis-detecting specific UUID values as strings.

Flyway had no such issues, and where I did make a mistake with Flyway, I got printed SQL exceptions rather than SQL exceptions that have abstracted by Liquibase. I encountered far less friction with Flyway.

u/hooba_stank via Reddit, makes the point that liquibase’s profiles grant it excellent flexibility. Using contexts in different environments, composing profiles for different testing requirements and conditional change sets and rollbacks make the free Liquibase offering compelling. It’s a great point.

Flyway’s requirement for sequential ordering of SQL files can lead to sprawl if you prefer small changes per file. Encountering failures becuase you’ve fat-fingered a SQL script version number is annoying too. u/koreth adds that this problem can be avoided by configuring a pre-commit hook and CI check to detect conflicting sequence numbers so this issue can be automated to a degree, though ideally it’s not something you have to deal with at all.

Wrap Up

Both Liquibase and Flyway are better than nothing by far. My personal preference is Flyway. Flyway is cleaner to implement and easier to use on an ongoing basis and more readable. That being said, Liquibase is a powerful tool. Chosing either of these tools to use in your development will give you good gains in productivity.

There are several things we need to understand about ourselves if we are to remain functional while under pressure. We need to understand what our baseline stress profile. We need to learn about how to work on our stress levels over time. We must deal with spikes.

I believe that Covid-19 is a long-lived global pandemic, that will shift the way the world works. Now, or over the next 12 months, our society will have to make changes to the way we live, together. If we can change, we may endure, after we endure, we might be able to start living again. We are not in a sprint right now. We’re in a marathon. Consider the pandemic an endurance sport.

With the recent announcement by the Government of Alert Level 4, it’s time to confront uncomfortable truths. Fortunately, doing so is the first step we can all take to adjust to this new reality. Confronting uncomfortable truths is the first step I’d like you to consider.

Credit: Allex Villegas, Twitter

Take stock of how you are, right now.

How are you feeling? Do you feel loose, calm or limber? Do you think you might evaporate into thin air any second, or perhaps you feel like everything around you is vibrating or spinning?

The very first step here is to figure out how you are responding both mentally and physically. Hopefully, you know what your body feels like when you’re feeling nervous, it might be trickier to figure out your mental state. Asking your mind to observe itself, is like trying to look rocks at the bottom of a pond without disturbing the surface.

If you’re not sure how you feel (or you feel busy but can’t quite narrow down why), you might find it useful to do a body scan. A body scan is a valuable mindfulness technique to begin to understand how you feel.

It’s important that during a body scan, you don’t judge yourself. Don’t beat yourself up at how you feel. The way you feel, is. The way you feel must exist free of any value judgement - our goal here isn’t to fix or solve anything. Our goal isn’t to make you feel better - yet. With a body scan, all we want to do is gain awareness of ourselves, in a way that we might not normally do.

There are several apps out there that can help you practice your body scan. I’ve had good results with both Calm and Headspace, and I recommend them both to you.

Often after a long day in Afghanistan, I would find myself exhausted despite having not done anything of note. My shoulders would feel like slabs of iron, and my back would feel brittle and inflexible. I didn’t know why. I slowly learned that the more time I spent trying to sense how individual parts of my body were feeling, the easier it was to find ways to accept how I felt. Allowing that I felt a certain way let me choose where to intervene, or where not to.

The effect this had, is that it took me from a place where I felt like things were happening to me that I couldn’t control, to a place where I could step back and examine what was happening, make sense of it and respond. I was able to reassert some control over my situation.

Regaining control in this way led me to a core concept that you may have heard before: You cannot always control your environment, but you can control how you respond.

Confront uncomfortable truths

Have you heard the phrase “Disagree and commit” before? Spoken initially by Scott McNealy of Sun Microsystems, Jeff Bezos popularised them as a core leadership principle of Amazon. You may have used these words before when talking about a decision at work. In this way, “Disagree and commit” can shape your reality at work.

They can also shape your reality outside of work.

The Stockdale Paradox states:

Retain absolute faith that you can and will prevail in the end, regardless of the difficulties AND at the same time confront the most brutal facts or your current reality, whatever they might be.

This concept was vital for me getting through the pressures of being deployed to a war zone. It can help again by giving us a life raft to hold on to during a global pandemic the likes of which we haven’t seen for a hundred years and more.

Practice with me now. Take these facts, understand them, and reflect on them. Take another body scan and reflect on how they make you feel. Be kind to yourself and know that this is a normal reaction.

This pandemic is global and will be with us for longer than our self-isolation. For the next year if not longer, you, I, our loved ones and people we’ve never met equally will be at risk of contracting, and being killed by this virus. Our careers, our families and our ways of life are at risk. It’s going to get worse before it gets better.

My two-year-old son is currently immunocompromised, and so I feel this risk very acutely. With practice, we can accept these facts and let them flow over us like water, and none of us is helpless.

I believe, and the goal here is for you also to believe in the core of your being, that we will get through this. We will endure. Of that, there is no question - as we have done before, so to will we now. We must have unwavering faith that we will prevail in the end. Having accepted entirely, the brutal facts of our reality, and armed with the conviction that we will prevail, positive change can begin.

Understand what you can control

Confronting the brutal truths of your new normal is the first step in reasserting control over your life. Regardless of what your chosen list is, make sure you have one. If your limbs feel like lead getting out of bed in the morning right now, it can feel gratuitous - why focus more on the things that make me feel this way?

Avoiding the truth will make you feel good in the short term, but only the short-term. It’s no way to live in anything other than a sprint, and as I said earlier, this is a marathon. If you need to avoid the truth to get through the short term, be kind to yourself, accept it and move on - but make a plan for how you’re going to eventually accept your situation in the same way you accept that your behaviour is what you need to do right now.

You will have worries; you’ll have confronted the world we share and the events happening around you. It can feel overwhelming, and you’re allowed to feel overwhelmed.

To accept what you can and can’t control, you need to be able to think about them all separately. Overseas, I struggled with being removed from my family. I struggled initially with the threat of death or injury lurking around every corner. I didn’t know the language and relied on others for communication that was vital to doing my job. I found myself bouncing around from small job to small job because it was challenging to think about the big stuff.

I adjusted. I had a scrap of paper in my barrack room that contained all of my worries. Writing them down took away the exoticness of them, but more importantly, it helped me to untangle them all. Rather than walking around as one big ball of stress, I could compartmentalise, and store little bits of well-identified stress equally across my body and mind. Once I figured this out, the process of dealing with it was much more manageable.

Accept what you cannot control What if someone buries a bomb in the road and my wagon drives over it and we all die?

For a soldier doing peacekeeping operations in Afghanistan, this was a genuine threat. It has happened before, to people you know, within the last six months. Nothing about this threat is remote or mysterious. If this happens, likely, you won’t even know about it. You’ll just be dead with a snap of your fingers, like that. Done.

How much thought should I have given the possibility I’d be killed by a roadside bomb the next time I left base? As it turns out, the correct answer: None at all. Let me explain why.

We had tactics, training, procedures - the Army spends a lot of time thinking about how to minimise this threat, and we have things that we do consciously and with enough training that it becomes subconscious, to mitigate the danger. Mitigate is the best case here. To altogether avoid the threat would require me not to do my job.

After you’ve done everything you can to manage your situation, what more can you do? Nothing. Accept that. What a beautiful thing! You’ve maxed out! You are now free to live your life!

Paraphrasing a good friend of mine called Epictetus (Discourses, 2.5.4–5):

“The chief task in life is simply this: to identify and separate matters so that I can say clearly to myself which are externals not under my control, and which have to do with the choices I actually control. Where then do I look for good and evil? Not to uncontrollable externals, but within myself to the choices that are my own . . .”

In other words, if you have made all of the choices available to you, if you have prepared as best you can, if you have reflected on what you can and can’t control, why should you focus on any choice other then the ones you own?

Acknowledging that your resources are finite and that you have done the best you can with them, you rob the power the uncontrollable has over you. You transform from “I don’t know!” to something as simple as “We shall see.”

Go through your mental list of worries and commit them to paper if that’s your style. Recently, I’ve tended to group and catalogue mine, and then speak them aloud, I talk about how they make me feel, what I can do about them and what I can’t do about them. In this way, I make them familiar, and I take away the power they have to shut me down. I take them from a place of power to a place of internal observation.

Create your new normal

By now, our old routines are gone. No more weekly sit-downs for Dungeons and Dragons, we have to go remote. No more dinner and drinks out. Social Fridays at the Pool and Bar are gone. While some folk continue to work in essential businesses, many will be out of work.

The old rules and old routines don’t apply now - take this as an opportunity to reforge your days in a way that works for you. I’m working from home. The creeping tyranny of meetings that could have been emails are turning into emails. I suddenly have time in my day.

Think about how you operate best. Are you a morning person? A night owl? Schedule yourself some time to exercise every day - staying active is essential, and so is getting fresh air. Stay in your neighbourhood, but do go for a jog. Schedule in some time for doing what you enjoy, schedule time for improving yourself. If you are able, consider scheduling in some time to help others - that may look like assisting a flatmate looking for work, it may be volunteering your time on the phone or making things to help people in the fight against COVID-19. If in doubt, apply this principle:

Spend time on yourself in the now, spend time on the future you, and give time to others; however you are able.

Importantly, build in time to check in with yourself. We started with body scans, why not create some time in now to keep up the practice? One of the best investments I’ve ever made in myself has been the scheduling in of mindfulness practice for a couple of hours a week. Other philosophies might speak to you more, but I’ve significantly improved my wellbeing by integrating regular mindfulness practices and adopting a philosophy of stoicism.

Track your progress

Allocate time (perhaps before or after your mindfulness practice) to have a check-in. Your body scans are an excellent place to start, and there are more practices you might build in then I can mention here (the internet is your friend!). Start with focusing on how you or your body feel now compared to last week. Perhaps spend some time trying to anticipate future stresses before they come along. Catalogue or internalise the things you can and can’t control, or otherwise seek to get ahead of things. Try to position yourself so that when the next wave breaks, you’re a little more prepared for it than you were last time. Alternatively, spend that time creating a place to retreat, a place where you can simply endure, and get back up again.

In Afghanistan, that place was the mess hall at Combat Outpost Romero. After a long patrol full of tension, knowing that I could come back after cleaning my kit, and sit down with a cup of tea and a hot meal and spend some time with friends off the clock made the difference between coping and thriving.

With your regular check-ins, you should be on your way to coming to terms with external stress. If you’re not, that’s okay. Remember that it takes time, and everyone is on their own journey. Be kind to yourself and others. If you don’t make immediate progress, or you do make progress and later lose that progress, give yourself some grace. Adjusting is complicated and is never truly over. What matters is that you’re making progress!

In the words of another influential author, Dr Seuss (Oh the Places You’ll Go!):

“I’m sorry to say so
but, sadly, it’s true
that Bang-ups
and Hang-ups
can happen to you.”

“But on you will go
though the weather be foul.
On you will go
though your enemies prowl.
On you will go
though the Hakken-Kraks howl.
Onward up many
a frightening creek,
though your arms may get sore
and your sneakers may leak.”

Stay connected - but consider avoiding social media

More than ever, it’s essential to be part of a community. Humans are social creatures. During stressful times we band together. Some of the tightest tribes and units I have seen have been built through shared adversity. I’m well aware that the literature out there says that teams and bonds form through positive reinforcement, but I cannot reconcile that with my own experience.

The tightest, most trusting, highest quality teams I have ever had the honour of being a part of, have been formed as a group of people were put together, and repeatedly flung into the shit. Be that on the sands of Afghanistan or after one dogshit, irredeemable project after another. The most potent teams I’ve observed have become like family in the positive sense of the word, not the exploitative “work until midnight because the company is your family” spirit of the word.

Connect with video calls, voice calls or text-based messages. Maybe it’s a long-running game of scrabble on your phone; perhaps it’s a Minecraft server you’ve set up for the crew. Find a way of staying connected remotely, with those you care for. Even more than usual, make an extra effort to keep in touch with those who might be more isolated than you. The oldies who are still trying to work their new iPad or the neighbour kids whose parents are working 16 hour days at the local supermarket - connecting with others will help your wellbeing and theirs.

Scrolling through Twitter for 4 hours a day will likely make you feel worse. Sifting through your Facebook feed for that one image a friend sent you might not be worth it. I have long-standing issues with facebook’s privacy practices, and have disabled my profile (and even now I encourage you to do the same) - but Messenger is a good way of keeping in touch even without a profile.

There is evidence from studies that say at the best of times; social media can harm our wellbeing. These are not the best of times. I’m avoiding social media as much as I can, and where I can’t, I’m changing my habits to reduce the time I spend on social media. I strongly recommend you do the same.

Dealing with pressure spikes

Themes have emerged throughout this article. Some of them have been deliberate actions we can take on an event occurring; others have been more general strategies or ideas to review. Here’s a summary of the tactics you can use to help manage your stress levels when the pressure is high:

1. Assess how you’re feeling - are you in a good place to face the wave as it comes in or a not-so-good place? Don’t forget to observe the body as well as the mind, as best you can. With practice, you’ll be able to take stock of how you are feeling, and anticipate how that might change as the wave approaches, breaks and recedes.
2. Examine the stress as you see it approach, and begin to accept that there will be some aspects of it you can influence, and some you can’t. You’re not a dummy for being unable to control some things, that’s life! Realising that you can only do your best will help you begin to regain control.
3. Look at your environment, and if you have time, make changes so that when the next stressor arrives, you have choices. If you feel you can withstand it, confront and mitigate it as soon as you can. If you’re feeling vulnerable, or you’re not sure you can tackle the stress head-on, find the place where you can endure, this too will pass.

In creating your new routine, you will have created a new you, a more resilient you. I’m hopeful that if you’ve got to this point, not only will you have adapted to COVID-19, you will have adapted to stress in general. You’ll have new tools you can use to remain active. You’ll have novel ways of integrating stress into your life while also allowing it to drain away, receding like the high tide. I believe that practising mindfulness, adopting a more stoic outlook on life, and being kind to yourself and others will improve the quality of your life, now and for the future.

Above all else, as Prime Minister Ardern says, be calm, be kind, look after one another.

Some of these things are not like the others.

Have you heard the phrase ‘digital’ so many times it loses all meaning? Try saying it a hundred times and see if the word still sticks in your brain. If you’re like me, it’ll slide right away like a fried egg off a bald head.

Now imagine baldy over there is your company. It’s risky for a thing to be so pervasive that one cannot escape it, or mentions of it (or articles about it - no the irony is not lost).

The problem is that there is so much work out there, and so many things that could do with a digital transformation (my thoughts on that phrase here), it can be challenging to find a place to start.

As Laozi stated, a journey of a thousand miles begins with a single step. How do we identify that first step? More importantly, how do we ensure that the thing we’ve identified is in fact, a first step, and not the first mile, the tenth mile or the hundredth mile?

Mark Rosenberg commented on a previous article. He stated that based on his experience, while you can educate the entire org on what becoming digital means, it’s often a challenge to digitally transform an extensive portfolio. Mark went on to explain that the most important thing to get right when considering what to paint with the digital brush, is defining the outcomes the business wants to see and then aligning use cases.

These comments paint the picture of a large organization looking at change, as being best served by starting small. By starting with products in verticals relevant to a business’s chosen outcomes, and the teams that look after those products, you provide people with a tangible start and endpoint, clear boundaries, and the most important thing of all;

Psychological Safety.

No betting the company, no gambling the product, no guessing the market.

Starting without psychological safety can be ruinous for your efforts to change. I’ve previously experienced executives lock up and be unable to make decisions. I’ve seen relationships between colleagues ruined because what is evident to one incites a fear-based response in another. I’ve seen trusted advisors turn in to detractors that actively try to undermine the effort to change - because they don’t feel safe! For a staff member reliant on the company for their living, the prospect of profound upheaval starts ringing alarm bells, and they aren’t bells that can be un-rung easily.

When you come to make the change, be that making digital your default proposition (what does that even mean?) or just applying a digital lens to the way you currently work, you enable staff to participate fully. You empower them to work without worrying about the blowback of a mistake made while learning.

Starting small in this way can also be kinder on your customers. Rather than presenting as a different company overnight, with diverse offerings or a different business model, we can offer a more compassionate, thoughtful approach.

Recall when the company that makes your favourite product ‘went digital’ - they turned off the call centre and switched to an online, email-only support model because it’s digital and it’s cheaper. I’m not sure what was more irritating, waiting on hold for half an hour or waiting three days for a job to be done that would usually have taken a five-minute conversation with a human. If you focus your change on the wrong things or are in it for the wrong reasons, your customers will suffer.

Thinking more about selecting that first step, though, it feels like you could approach the question from multiple angles. In heeding Mark’s advice from earlier, you need to ensure your company has set those outcomes for you to draw on. Assuming you’ve done that, you can take those outcomes and ask yourselves the following:

A Choice appears:

Of these outcomes, which one is the most valuable to our customers?

Or

Of these outcomes, which is the easiest for us to achieve as a first step?

What’s the risk?

Your answer will likely depend on your risk appetite. Personally, working to deliver the most value to customers feels like the best approach. Should you achieve that outcome, you have the best chance of your customer base, rewarding you via the bottom line. On the other hand, should this outcome not be achieved or should you not provide the right solution, you’re also much more exposed for the same reason.

Thinking back to when I had to make this choice, my focus and customers weren’t the primary revenue stream for the business. For me, in my role, ‘most valuable for Alex’ was not ‘most valuable for the business’. It was a weird time on reflection. I could take on a risk profile that was a bit more aggressive than might fit your context. While it was the most valuable thing for my area, it was a natural step for the business to take.

Where risk is a more significant concern (or perhaps when you only have one essential product that drives company revenue), the safer option is usually to tackle a smaller option. I won’t call them low hanging fruit because, in my experience, low hanging fruit tend not to exist. They are tricky problems masked by a lack of understanding or data. Instead of creating new teams or new ways of working, or creating new products that need love and investment, begin by conducting user research with a focus on that small problem. Please share what you learn and then act on it.

Early on, it’s crucial to share what you’re learning with the business and your stakeholders. Once you’ve shown the knowledge you’ve gained, deliver a change to address that knowledge. If you can show that you’re learning from stakeholders, learning from customers and then applying that to your product, you build trust with all of those parties. Importantly, you create trust in a way that is difficult to argue. The data tells all.

I chose to look at a particular feature that wasn’t working well in a product. We asked some customers and non-customers to come in for interviews, ended up with a bunch of feedback that we then took to the business. We had to challenge some folk as the feature had been designed initially based on gut feel. Engaging them as equals from a position of psychological safety meant we had a fruitful and robust conversation and were able to produce and deliver the product increment.

Snowballs get bigger as they roll

In the same way that you might snowball your debt repayments, snowball how you deliver software. By demonstrating you can create with a customer-focused approach, and by tying that to the results the business might see, it becomes a lot easier to justify more substantial changes. At the same time, you are building confidence that you can deliver that more substantial change.

None of this requires Agile, Scrum, Kanban or whatever else. It just requires talking to stakeholders, talking to customers and responding to what you learn. If you can design this feedback loop to be short, and become more responsive to the market rather than driven by a project plan, you’ll be in the right place regardless of the chosen framework you want to use.

To me, this is pure business agility. There’s no rocket science here, but it does require the things you started with, back when the business was young. It requires humility, a willingness to change and grow, and a willingness to get stuck into some problems that may be hard, ambiguous, poorly defined or a combination of those things. Big businesses can lose that mindset as they become more process and governance driven (read: risk-averse) with growth.

I mention business agility because there is an implied link between business agility and speed or pace, and pace is something that a successful digital initiative can give your business.

I believe that the hallmark of a digital business is pace. Not technology or software or design. Pace in all things. Digital transformations are lucrative because of this. Operational and organizational tempo gives corporations the ability to turn on a dime and respond to market forces, legislative changes like GDPR, crises or opportunities. Digital is eating the world. It will keep coming up again and again.

Snowballing improvements to your product or chosen outcomes demonstrate pace. We start small or start with one thing. To start big is too risky for the business. It threatens too many people needlessly. It works against the goals of the transformation.

Pace

We’re not doing digital for digital’s sake; it’s pace we want. Replacing a paper form with an electronic one doesn’t automatically please your customer. Responding to customers in minutes, rather than days certainly does though. Amazon is still selling books. The difference is that now you can access a wide variety of literature online (more then your local bookstore would have in stock), order online and reasonably expect your order to arrive in a day or two. The days of having to wait for a week are gone. That’s pace. Digital, and the technology behind digital efforts, are simply an enabler. I’m sure that nobody at Amazon will ever regret investing in getting books to customers faster. Likewise, it’s unlikely a business that has tasted pace would regret it, even given the cost.

Getting back to our research, and the action we’ve taken; start small, get the knowledge and deliver that to a user. Even if it’s a limited section of your customers, that’s still good. If you’ve done it once, do it again. Rinse and repeat. As you become more familiar with the process of learning, building and showing, this feedback loop begins to feel natural. It should start to feel better than the way you used to work. It becomes the default to ask customers about their problems and views on your product before starting a bit of work. These lessons begin to show in other parts of the organisation. The organisation begins to think more about pace and more about how they might use technology to become faster. You encounter a turning point. The default position becomes to use digital methods, channels (and the technology behind them) to solve customer problems.

Your digital transformation has begun.

In reality, it’s never as simple as this. Fortunately, by keeping your cycle time low and your work chunked as small as possible, we reduce the chance of significant problems, and hopefully, we reduce the damage any mishap might cause.

Some points to take away:

1. Your context and the outcomes you want must guide your efforts.
2. Keep the psychological safety of your colleagues in mind.
3. Make sure that the work you do aligns with the broader business.
4. Focus on the smallest thing, build trust and then tackle more significant problems.
5. Build with customers, not just with customers in mind.

Everyone wants to talk about digital-led businesses. Every business is a software business, even when they aren’t, people will tell you. But the focus on big bang, project managed, change agent-driven initiatives tend to leave sour tastes in the mouths of long-standing staff. Naive technologists or agilists or product people for that matter exacerbate this when they perform the business strategy equivalent of the ‘seagull’. Discontent frequently morphs into outright opposition, and emotion becomes the dominant decision-making force rather than observation and planning. Eventually, what good will the agent(s) had is exhausted, and they leave the business. Sometimes voluntarily, sometimes less so.

Thus ends the digital transformation — a practical exercise in how to win friends and influence people, speaking from experience.

The end goal was a digitally-led business, with a focus on experiences and the products that power them. The more I learn from others in the industry, the more I feel like this is still the right outcome. Is there a business out there today that doesn’t want the best for their customers? Is there a business that doesn’t want to shift their customers from high-cost channels to lower-cost channels, while at the same time improving the experience those customers have? Is there a business that doesn’t want to maximise the lifetime value of a customer in a way that is engaging and delightful? Even companies that might not have the words to describe this nirvana surely want that for their customers and their bottom lines regardless?

The core assumption.

The core assumption I’m making is this: Businesses want - and have always wanted - highly engaged, happy customers who pay more money for the goods and services that business provides, while at the same time reducing costs as much as they can.

The thing that differs then, is not the goal, but how we get there as a group. The big question businesses have then is not the what, but how. Is it a shift in the customer segment or vertical? Is it the pursuit of new markets in new ways while maintaining old markets and old styles? Or is it a digital transformation? How do you decide when it could be any of these, at any time and in any order?

These are the questions that every digital, agile, product, devops, rockstar ninja consultancy on the planet have solved they will say, breathlessly in the white paper you paid for with your email address. Some of the claims might even be true. I don’t believe in any of them. The majority of the movements I see in industry pros look to digital transformation as the next step for any business. The approach: Hire product owners and managers, or shift the ones you have out of the marketing department. Let them be the agents of change as surely they will rally the business around them in pursuit of the customer! Customer Obsession will carry the day! Last time someone took that approach with me, I was made redundant. From what I’ve seen such things end one of two ways. Either you force out the existing staff that built the business, or the agents of change don’t get the support or cut through they need, and they move on. Losing momentum is the most significant risk with a transformation. By definition, it has a beginning, middle and end. A transformation implies a shifting of the status quo, techies, product people, design and experience folk are hired into the business with a mandate to change the way the company has worked up until that point - because if you don’t change you don’t transform. Those newbies to the business have new ways of working, and the implication is that those new ways are inherently better or more suitable for the company than the old ways that we built the business on in the first place!

This attitude implies that the newbies are inherently better or more suited than the existing staff that built the company and a collision point arrives. These groups clash until one group wins, and one group loses. I haven’t seen a clash like that de-escalated successfully.

Why then is there such a focus on a transformation? Why are we doing to entire businesses what we now try to avoid doing with the software that we tell companies they need to be thinking about first? As an industry, we’ve been attempting to move away from big bang releases on a Friday afternoon. Why do we treat whole companies the same way now? If we can figure out how to de-risk deploying and releasing software, surely we can focus on doing something similar for businesses that want to participate in a digital-first world.

Think about integration, rather than transformation. Rather than seeking to supplant, subvert or replace, we should be looking to merge, join and integrate.

In tech we try to remove silos. Why stop there?

How many times have you seen a technology team working siloed, away from the rest of the business? The predominant practice used to be waterfall, where the teams hide down on another floor for the entire duration of the project, only coming back to show the business what they’ve done at the very end of the budgeted time. Agile and Scrum have advanced that, now we talk about what we’ve been building with our stakeholders every few weeks (two weeks being most common). That’s a great achievement compared with waterfall.

With this way of working being a next step on the journey, what comes after that? Once you’ve got mature teams experienced with this way of working, it can happen that the product owners, design team and other team members are doing regular customer research sessions. Staff process that data into insights and product improvements. Next, they build that feedback into their digital products. The new approach works up to a point.

Eventually, it becomes difficult to improve some aspects of the product because the tech team might only own the digital representation of that product. Take a bank for an example close to heart. Suppose you get some feedback in a user session that the fees charged on a product make it unattractive to the user. Your tech team is incentivised to fix problems with the digital product. Still, now you’re finding issues with the traditional representation of that product - you can take that feedback back to the bank, but you’ve just hit another silo.

We’ve come so far in building cross-functional technical teams and cross-functional software product teams. The next logical increment is the cross-functional business team. When you think about the time before ‘digital’ existed as a thing people wrote white papers about; you’re just describing a regular team as we’ve seen for most of the history of business.

You might find that this is not a case of digital eating the world, or technology changing the way we do things. Such statements are arrogant and misguided. The way we position the concept is that there is something inherently better about us and the rest of the business world is lacking. It’s like the scrawny new kid on the block hit the gym and got monstrously huge over summer and is now flexing nerd rage on the rest of their class.

We should not be seeking to replace the old world order of business; we should be augmenting it. We should not be trying to transform our lessers. We should be using our skills and technology to push the entire company forward.

A kinder, more empathetic way is needed.

Suppose we had a business team that consisted of a domain product owner, digital product owner, a couple of developers and testers, maybe an analyst, devops type person and designer. Or suppose we took an existing technical team and asked that the principal business stakeholder joined that team, co-located and contributed permanently.

That pesky fee that’s turning off your customers in digital and retail channels could be solved quickly. Whenever the digital folk were undertaking a significant software initiative, they would likely already have the backing of their crucial stakeholder. That stakeholder would already be up to speed. They would be the most prominent advocate for that team to the rest of the business. Through co-location, you eliminate a host of meetings and sync up sessions. Through a shared context, you ensure that the company is on the same page as the techies. Sprint reviews become about inspecting and adapting the backlog from a whole of business perspective, not just a technical or feature perspective. Is it more valuable to change the way the product works, or change the way we position the product on the website? Such comparisons of work become meaningful because we can find an answer, rather than being thrown out there and not picked up by anyone.

This approach is by no means a panacea. It is still hard work. The nominated business person and the team still need to learn how to work together. What might seem like an unbridgeable gulf in some places could be just a very very large chasm - bridgable but with effort. The rest of the business needs to back such an endeavour. Come from a place of equality, rather than superiority. Acknowledge that your colleagues paid for your ticket here rather than expressing surprise they haven’t choked on a peanut before now. You’ll have a much better chance of success, without resentment and without forcing anyone out of work.

What do you get for success with this, as opposed to a digital transformation? For one, you can unsubscribe from all of the consultancy mailing lists cluttering your inbox. More importantly, you’ve empowered a group of people with experience across the digital divide and set them loose on the toughest problems your business has. By working incrementally (rather than in a big bang project-driven way) you de-risk the effort. You can manage the pace and spend (reducing pressure on staff old and new, and pressure on the bottom line through less staff and hiring costs). You also ensure that all of your team are engaged and working in the same direction, not just the subset of staff who have the wind behind them.

This is just back to basics.

What’s ironic is that this way is the way all business began. There are no silos in an eight-person business. In a way, we’re just getting back to basics. There’s poetic symmetry in that somewhere.

If I owned a business, and it was my money and legacy on the line, I’d avoid a digital transformation like the plague. I’m not in that position though, so I’ll leave it to the reader to pick up the torch.

Why have a lab

Having a lab represents freedom. Freedom to learn about new ideas in a safe space, freedom to use many different tools to make your life at home better, easier or more automated and freedom to build something new that eventually others could be involved in.

A lab is anything you want it to be. In my case it’s an Intel NUC and Raspberry Pi running various versions of linux as a base, with many docker containers on top. For you, it could network storage equipment and backup power supplies, it could be a big server running virtualisation tools or even a whole bunch of Internet of Things devices. Part of the joy of having a lab is that it can reflect your current feelings and priorities, and be flexible enough to change in tune with your priorities.

Working at the right layer of complexity

For me, the most important things in a lab are that I’m using the right tool for the job, and that I’m working at the right level of abstraction. In my case, I’m running a lab at home to automate parts of my life, enable the building of my own software product (maybe one day I’ll launch it in to a startup!) and that I can make the internet a better place for my family. To that end, I’ve got many tools running at home that fit under those categories (and some that don’t). Let’s first talk a little about what I’m not doing.

• I’m not currently focused on how networking works
• I’m not currently looking at configuration management and how that works (I’ve got some experience with puppe though)
• I’m not currently interested in virtualisation, hardware security or hardware in general

Another way of saying this is that right now, I care about applications and how they talk to each other, I don’t care about the underlying infrastructure (unless that has a material affect on the applications themselves).

So my chosen layer of complexity is the application layer, that means that where possible I should find a way of removing the complexity below that layer. This is not to say I don’t care about what hardware I’m running, it’s to say that I don’t care beyond a certain point. My low maintenance lab consists of three key devices right now.

• Networking: 1x Netgear Nighthawk X10 R9000
• Compute: 1x Intel NUC i5
• Compute: 1x Rasberry Pi 3b

It’s worth reiterating that my focus here is low maintenance. That means simple hardware, and low running cost. The Pi costs about $8 in power per year, the NUC a little bit more, all of this equipment runs cool and quiet. It’s also not overkill. For me it’s more important to have the right kit at the right time, than it is to have plenty of room to grow. I could have started with a big network attached storage device and enterprise grade server, but that’s a bunch of cash I don’t need to spend right now, for a hobby that might not be around in a couple of years time. It’s going to be slightly more expensive to scale because of this. For example the RAM on the NUC tops out at 16gb, at the moment I have 8gb with one slot left. If I want 32gb of RAM I either need a new server box, or another NUC. I’ll probably get another NUC. I think the tradeoff is worth it.

Raspberry Pi - Network Services

The Raspberry Pi 3b was actually the first thing I bought, at the time I wanted to make a retro gaming box for my kids but they’re still a little young for that. Now I treat it as a tool for network services. It’s my DNS server (so I can get gucci names for my services like $SERVICE.$MY_CUSTOM_DOMAIN.co.nz) as well as a network wide ad-blocker (thank you Pi-Hole !). I also wanted to run docker containers on it, but the ARM chip in it makes that a hassle. In the future I’d like to run a VPN from it, so that I can access all of my home tooling while I’m away from home but I never seem to get time to sit down and do that.

Intel NUC - General Compute and Storage

The NUC is my most recent addition, I picked it up in a sale last year. I’m pleased with how it’s performing and will probably scale out by adding NUCs until power management and things like that get annoying. It’s a 7th generation i5 processor, which is to say it’s not a beastly multitasking machine. It’s not and never will be good for things like rendering farms or bitcoin mining. It is however, good for a lot of moderate usages. I’m currently running 30+ docker containers (but more on that soon) and CPU usage hovers at around 3% idling, and bursts up to about 30% when it’s working hard. With how powerful entry level CPUs are these days, processors generally aren’t your bottleneck. It’s RAM - this is a very different picture. There is 8gb of RAM available right now, plus another 8gb of swap on the M.2 SSD inside the NUC. RAM usage sits at about 60% when idle, and maxes out fairly regularly. RAM is my next purchase.

Bare Metal, Virtualisation and Containers

For context, there is no right or wrong choice for you here. It really depends on what you’re optimising for. In my case, I want the regular maintenace of the systems and applications I use to be minimal and recovery from failure should be easy (reflecting the fact that I am highly likely to break the entire network and that this should be encouraged. It’s where learning happens). I don’t care so much about speed and efficient use of resources since the cost of scaling isn’t prohibitive, and I don’t really care about isolating things as a primary effect of the choice I make.

Business tend to have different needs so if you’re running a lab to skill up for work, your needs might differ.

For this reason I chose containerisation as my go-to application paradigm. It gives me the ability to store my application config in VCS, making recovery from failure alsmost trivial. With good orchestration tools I can manage resources well enough, and it also means that I can isolate applications from my underlying hardware. Docker is the de-facto standard for containerisation, and I’m already familiar with it through the work I did on continuous delivery for Healthlink and Spark.

That isolation from the host is important to me, as it means that I can treat my machines like cattle, not like a pet. With Docker I can take advantage of the underlying OS (in this case, Ubuntu Server 18.04 ) in a way that keeps the OS clean and tidy. All changes sit inside containers and not on the host OS - I can swap out Ubuntu with CentOS as many times as I want, my containers don’t care. I can upgrade the version of an application inside a container 300 times and the underlying OS doesn’t care. Things stay tidy. This also means that the process for recovering from a critical failure is small - application configuration is in version control, if the NUC grenades over the weekend, my recovery is to re-run that config on a new node. The hardest part of that is buying a new node because I hate spending money. The use of containers also mitigates some of the scaling pain. Rather than manually moving stuff from one machine to a new machine, or having to configure a bunch of stuff on a new machine, it’s easy to scale out the software side of the lab - all thanks to a tool called Rancher.

Container Management

It’s important.

Rancher is the tool I use for container management and orchestration. I consider it to be my one stop shop for all things lab management, and is the main view (I do have other views) in to the state of my lab. This isn’t a sales pitch for rancher as much as I love it, this is mainly about how I use Rancher to solve the problems I want to solve.

The feature I use most with Rancher is orchestration. I specify the config of an image I want to run (via compose file or via the GUI) and Rancher worries about what host it goes on, what other containers it’s grouped with and so on. When the container is running I can inspect it, run a shell to it or modify it’s config easily. Rancher also has an awesome concept - the catalogue, that contains many images and config maintained by the community, that you can one click run in the style of Sandstorm, Bitnami and Cloudron, except rather than just deploying the application, you can deploy applications ready to scale, with pub/sub queues, redis and so on already integrated in to the application state.

Rancher comes with a load balancer based on HAproxy that works well out of the box. It has integrations in to Rancher functionality that make it super easy to set up reverse proxies with SSL termination. I simply add my SSL certs to Rancher’s cert store, then select them from a drop down menu within the load balancer. I can apply custom HAproxy config to automatically redirect http requests to https, and can configure path or link based routing.

The final part of the Rancher puzzle for me is the config files I mentioned earlier. Rancher maintains vanilla docker compatible docker-compose.yml files for every stack of applications it manages, and updates that compose file when you make changes to the configuration. It also provides a rancher-compose.yml that is very simillar to docker compose, but provides rancher specific config (e.g start with 3 containers or 10 containers, and so on). This for me is crucial. All of that config is held in VCS and so if the machine grenades, my state is stored safely elsewhere. That;s just the container config though. There is also config specific to the applications, that tend to be stored within the file system - in this case, Rancher makes it easy for me to volume out all of the config to the host, I don’t back that up currently but am looking at cloud backups for that also. I’ll probably have a daily backup to some hardware I’m running locally, and maybe a weekly or monthly backup to a cloud backup service provider (the state of my applications changes very infrequently so monthly or fortnightly is probably the best compromise there for cost vs currency).

What I’m Running

Right now I’ve got several stacks running within Rancher. I’ve grouped applications around themes for those stacks so that it’s easier to see what capability I have running and what I’m missing. The stacks are called:

• Home Admin
• Network Admin
• Media Automation
• Media Streaming
• Product Development

I’ll run through each of them at a high level:

Home Admin

Home admin for me is mainly about automating the things that relate to the physical space I live in, aka my house. I’ve got Mayan EDMS running as a paper removal machine. All of my bills, legal documents and other official docs get scanned and added to shelves within Mayan, so that I can search on the text inside the docs instead of just for PDF names and so on. I’ve docker-linked to Mayan to it’s own postgres container - this is a pattern I repeat and abuse for all of the tools I run. As an aside, the reason that I do a container and database instance per tool is so that I have more flexibility to upgrade or blow away databases. It also means that the databases are clean with only tables and data from one application. I choose postgres because it’s what I’m familliar with. It can be a pain but it’s a pain I know!

I’m also running a janitor tool that periodically scans for images that have no active containers, and dangling data volumes. If it finds anything not in use, it deletes it. Since my config is all stored externally, I can be fairly ruthless in terms of space saving this way.

Network Admin

Network admin is a bit of a small stack right now. It currently contains a netdata instance for host health monitoring - Rancher has the ability to manage hosts but the reporting from netdata is much more detailed. The stack also contains an instance of Rancher’s load balancer - this is where the reverse proxy and SSL termination functionality comes from.

Media Automation + Media Streaming

My media automation efforts are the most complex stack. I’m using SABnzbd, Sonarr, Radarr, Ombi (half heartedly), Tautulli and Plex. My focus here is on making available all the Blurays, DVDs and other media that I’ve collected over the past 15 years or so. All the childhood movies whose disks got broken, the numerous copies of the Matrix trilogy that I somehow acquired and the stuff that I generally grew up on, that I’d like to share with my kids now that they’re getting old enough.

Product Development

This is the stack that is most actively worked on. It contains an instance of some software I’m developing in my spare time, a postgres database, an SMTP mail server and interceptor (for testing email notifications that come from the software I’m building), and an instance of the swagger editor.

Wrap up

This is a little bit of detail behind the thinking I went through when I decided I wanted to spend some time away from development, so that I could focus on learning about product and wider business things. Your lab might have different needs and look different, that diversity should be celebrated. There is no right or wrong lab!

I went with docker as it fit with my goals, those goals were about making the things I care about less, easier. That frees me up to focus on the stuff that I care about.

Rancher is cool.

Having just started a new role, the pressure to deliver and deliver quickly can be quite daunting. Using hypothesis-driven processes in your daily life can ease the tension.

A few caveats before getting started:

• This approach works best if your manager supports you. It can you can do it by stealth, or without asking (sometimes it works best if you don’t ask). Often you’ll get the best results if you bring the method to your team - that’s any managers you may have, as well as anyone that reports to you, or colleagues with whom you work.
• The stories I tell are from a software context; I believe that these processes can be used in different settings, but remember to be thoughtful about how you do that, don’t forget to test and adjust as you need.

Definition: Hypothesis

• A supposition or proposed explanation made based on limited evidence as a starting point for further investigation.
• A theory before it’s tested. A hypothesis like a theory should have both explanatory and predictive value.

In your everyday work, you have some impacts we want to achieve, be they strategic (increasing profit or reducing cost) or tactical (increasing daily active users by some proportion). Traditionally you might approach those goals any number of ways. You think up a solution and execute on that. You call time on the mission and move on to the next thing. And the next thing. And the thing after that. Project managers often get a bad rap for this, but it’s symptomatic of the business rather than the project manager in many cases. Those managers aren’t being incentivised to return to things and assess benefit since, in many cases, the contract has already paid out and to do so would not get them any more value for the business.

Enter stage left, the scientific method

For hundreds of years, people who have no idea what to do, have figured out what they need to do by using the scientific method. It looks something like this:

I’ve made some slight tweaks to the technique, the team here use this flow to manage the delivery of one to many features that will result in actionable insight. We’ve found that building a process where we are regularly looking at the outcomes we’ve achieved in the context of our goals, and work remaining helps us keep on track. Being mindful of business objectives reduces context switching - when the business makes requests, we can point them to data if we have it on why the demand may or may not affect the goal, we can also use the findings to help us prioritise. Those findings show financial value to the business and value to the customer. If someone asks us for some work, we’ll be able to look at the cost of that work, the opportunity cost and the likely benefit we might derive and give data back on how that will affect the backlog and the results we might see from the team.

The Method

Start with an impact that you want to have on someone - it could be a staff member, a customer or some other kind of stakeholder. Once you’ve defined the impact you want to have and formed that into a goal or objective and key result, you can start building context.

Doing background research and getting that context can often be the most costly step in terms of time spent. If there is a mountain of existing data to trawl through, it can be quite a tedious process. Persevere! It’s worth it. The more insight into the issue you can get before you form the plan, the better. When I’m going through this process, I’ll skim the available documentation first and ask myself “Will what I’m learning right now make me adjust the plan, or does it answer my question or address my goal some other way?” - If the answer is yes to either of those things, it’s worth the extra time is taken to make those adjustments. In some cases, you can skip the experiment altogether and prove out your goal by combining multiple existing sources of data in a new way. The time and cost of gaining that context can save you the time and cost of the rest of the process. You can skip straight to the analysis and dissemination of that knowledge.

Forming your plan is where most of the risk in this process sits. If you are missing crucial data, it can skew the method such that the experiments become questionable. If you’re doing an investigation into how to reduce the number of times a boy cries wolf; You should try to understand that humans lie a bunch. You might miss that sometimes wolves appear despite the local shepherd boy having no credibility. Standing in a field cataloguing the presence or absence of Canis lupus won’t get you closer to an impact or answer.

Further, if your plan is missing crucial information on what data needs to be tracked to prove out the experiment, you’ll struggle to show that the desired impact has been affected.

In an ideal world, you should have a strong hypothesis that can be tested independently of other work going on, that hypothesis should relate to the goal, and the experiments you design should provide you with the data you need to validate or refute the hypothesis. Sometimes it’s hard to get the information you need, or it’s hard to run the experiment in isolation from other changes. That’s okay. From the research you’ve done getting to those points, you should have a good feel for how to mitigate those concerns or make a call on whether or not the experiments should proceed.

After you have designed your experiments, the next step is to run them as per the plan. It’s essential that during this time you rigidly stick to the program (unless it has become unsafe, unsound or otherwise untenable). As you run those experiments, it helps to note down during the process any points for improvement for next time. If the tests are not running as you expect, those points you’ve noted for troubleshooting or development will help the experiments and the way you design and reason about trials evolve as your understanding grows.

Your experiments have run the course; now it’s time to analyse the data. How you might do that is a little out of the scope of this. There are several methods for synthesising that information in both qualitative and quantitative ways. Once that process is complete, the write-up can begin! It’s essential that during the write-up you clearly and plainly state one of three things:

• Has our intervention made a positive impact (i.e. are we closer to our goal now?)
• Has our intervention made a negative impact (i.e. are we further to our goal now?)
• Has our intervention made an impact that we can see? (i.e. have we been tracking the right metric in regards to the impact?)

If you can clearly state one of the above and back that up with the raw data that proves out that point, the rest of the write-up falls into place. You can spend more time talking about what happens next, and more time socialising those results. Either way, it’s essential that the research you have created is filed away in a place it can be easily referred to, as it now forms part of the ecosystem of knowledge you have to draw on for the next goal, hypothesis and experiment.

The Difference

he difference between these two processes is less about the process and more about the context. It’s relatively safe to assume that if you’re doing science in a scientific domain (at a university, technical institution or somewhere else) you often have a large body of work to draw on that is formally named, has been cited a bunch and published.

Sometimes in a private company, you don’t have that body of knowledge to draw on. Maybe you have an internal wiki, or perhaps documentation is spread across a bunch of shared drives. This process gives you a place to start. Starting with this process will help you generate that body of knowledge (which you should then store in a tool that can be accessed by whoever needs it). Being able to draw on that research takes the ego out of conversations about how to achieve goals. Having a team follow this process can also help you avoid distraction, as it’s clean, simple and ideally short if you’re working down in detail. If you’re not working at that tactical level, you can also use this process to plan work out across the business - for each high-level initiative, you might repeat lower-level versions of this initiative many times with different foci.

It’s important to note that there is no failure case in this process. Should an experiment not yield a result you expect, that’s okay. There is no value judgement or loss of face there since we acknowledged at the start that the hypothesis is only a best guess and that ultimately the data will tell us the answer. Regardless of the outcome that knowledge gets stored and becomes part of the institutional experience that can now be built up - help others in your organisation, use your lessons in their work.

In this way, we can start creating an ecosystem of research that we can use to reinforce our learning and experiments. It means that we can build and extend on our body of knowledge each analysis we run, in a way that relies on empirical data and processes that can’t be argued with or litigated (assuming the methodology behind your research is sound). If your organisation has a problem with pet projects that deliver questionable value (I’ve seen and heard about this problem in many organisations), this process is excellent for having a conversation about whether or not this is the best thing to be doing with the resources available to the business.

Speed to Market

Executing work in this way can be as slow or as fast as your business needs it to be. For domains that require high certainty and minimal risk, we can make choices about how long we run experiments for, we can limit the number of users involved in the research, and the defined process can help you include other parts of the business. As part of the context building step of your experiment, you can reach out and involve other teams or people if you have that specialisation available, and if you don’t, that’s okay too because there isn’t a commitment to the experiment long term unless that suits the business.

Should you be in a domain that encourages rapid iteration, short experiments with a large number of users can help you sense and respond rapidly to the market. Borrowing heavily from lean methodologies, you can focus your effort on the successful experiments and quickly discard ideas that do not help you achieve your goals.

You still need to prioritise

Applying the scientific method in your role doesn’t replace the traditional process of prioritising work. It remains vital for everyone involved to understand what the most important thing to do is and why it’s crucial. Whether you use the Kano model, Outcome-Driven Innovation or something else entirely, those goals still need to be looked at in comparison with other purposes. This method tells you whether or not you’re moving the dial, and whether or not you should keep trying to move the dial the way you are currently trying to move it, or if you should change or stop.

Conclusions and key points

The scientific method is an established, proven way of learning new things. This method is something that can be used in a business or technical context as much as well as in academia.

Using this process, or basing your process on the method can help you understand new situations and contexts in a way that is safe, rapid and applicable to many domains or industries.

It helps if you’ve got buy-in from your organisation, but ultimately you can use this process to guide your work internally within your team, or on your own, if you don’t work as part of a team.

This process helps you define a goal, and plan interventions to shift a metric on that goal - it then encourages you to show others the results and use that new knowledge as part of your future work.

References and further reading

[1] Hypothesis-driven development - Dr Dobb’s World of Software Development

[2] Experiment driven development - Sebastien Auvray, InfoQ

[3] How to implement hypothesis-driven development - Barry O’Reilly, Thoughtworks

That’s all well and good, but what is the point?

The point is that good teams are rare. That is to say, a team that you can leave alone, with the trust that they can self-regulate, self-correct and grow without you is very difficult to find, such that the effort to grow one (if you can) is a far simpler thing by comparison.

In a world where everyone says they put users first, but very few actually walk the talk, you need teams like this. You need them because there is simply too much stuff going on for anyone to keep track of. Particularly at a place like BNZ. We’ve got work coming out our backsides. BNZ Digital is a small part of the wider Bank. Dunbar’s number is 150. Dunbar’s number describes the amount of stable relationships a person can have - relationships in which an individual knows who each person is and how each person relates to every other person.

Teams are important because they increase Dunbar’s number. I can abstract away up to ten people and hide them behind a single team. I can align those teams with products or purposes or causes or constructs; it’s natural for organisations to grow, grouping employees into teams helps us keep it all in our heads at once. It helps us maintain cohesion and coherence.

But getting back to the users, they don’t see all that complexity nor the size of the issue you’re trying to fix. They don’t care about the complexities of OAuth 2.0 or how difficult it is to scale things without blockchain or the latest facebook framework. They care that in the year 2018 they still have to log in to internet banking with a number we gave them.

Imagine the cognitive dissonance. On the one hand, the bank has spent time and effort on an ad in between the ruggers about how important I am to them personally, and on the other, they’ve literally set my internet banking login to some random number instead of my own name or something meaningful to me. Neat.

Good teams show users that the team cares. Good teams put users first. Yes, the Product Manager has given you metrics to move and the head of department wants a big splashy thing. The salespeople want more conversions and the brand people want you to speak with one voice and feel with two feet, or something equally as nebulous. Who knows what that other team wants. They stopped coming to meetings ages ago.

Good teams know. A mature, high-performing team can work across the business and manage that entire lifecycle of work. They can start with discovery and research, ensuring that they’re working on a valuable problem that if solved, will make a happy user. They can plan and execute the work, and importantly, know when to involve people from other teams and disciplines as needed. That other team didn’t turn up to the meeting because we’d spoken to them previously. Brand is happy since they saw the copy weeks ago, and actively drafted the content alongside the content team. Of course the software is being written and tested, eventually deployed and importantly, the impact of that feature on the user is measured.

All this is not to say that if you’re not doing the above, you’re not part of a good team. Everyone’s context is different and that should be celebrated. We all get value to our users in different ways and that makes for diverse companies that compete, learn and grow.

Context

We’re a Health IT company based out of New Zealand, and run an set of products that provide messaging integrations between Healthcare organisations across New Zealand and Australia. Our applications are a mixture of desktop and web service based, and we’re currently undergoing a massive change process from Waterfall to Agile and from a bespoke services company to a truly product focused company.

The Problem

Our time to market is poor, we want to shorten our release cycle and provide and awesome service to our customers (above and beyond the services that basically enabled us to become a monopoly in New Zealand).

The Solution

To enable rapid iteration, we needed to shorten our feedback loops, and the best way of doing that is by implementing continuous delivery.

The Principles of Continuous Delivery

There was quite a but of work to do to enable our solution, continuous delivery has a bunch of prerequisites and we wanted to abide by a set of core principles that would guide the technology and process decisions we made.

The principles that guided us are:

1. Processes MUST be repeatable and reliable.

   • The process by which we deploy our software has been automated, but often full automation of a release can make the business uncomfortable. To help the business get used to this, we’ve introduced some decision points in our release flow that require manual intervention.

2. EVERYTHING has to be automated.

   • The manual decision points we’ve introduced don’t violate this because no process is actually being done manually, we’re just providing business the opportunity to control the process in more discrete steps. All of our build, test and deployment steps are automated though, that in itself has reduced our time to any arbitrary environment to about a minute, with full unit, integration and system tests conducted every time we build and deploy.

3. You must be able to guarantee quality.

   • The bedrock of any automated process is quality. We guarantee the quality of our code by monitoring our code metrics in Sonarqube - things like test coverage, technical debt and best practice conformance. Sonarqube breaks builds if they introduce issues or lack test coverage on new code. Further, in tracking unit test coverage, we also ensure that those tests are run and pass - if you don’t use them, there’s little point spending time and money creating and maintaining them.

4. If something is difficult or painful, it must be done more often. You can’t build muscle without exercise.

   • In forcing ourselves to do painful things often, we worked out the issues in those processes and were able to mitigate or resolve them entirely, leading to a much more robust process.

5. Everything must be expressed as code and versioned.

   • Obviously our application code is all safely in git, versioned and lovely, but it’s important to version and code our build steps and infrastructure as well. We achieved this using Puppet with Hieradata within a git repository managed with Puppets’ Code Manager, and docker allows us to store our image creation steps in a Dockerfile, which is stored side by side with the application code itself.

6. Things are only considered DONE when they are released to Production.

   • Setting up triggers such that successful deploys off a dev branch trigger builds and deploys on our master branch enabled us to smoothly flow code through our environments in and automated way. Bamboo gives great deployment functionality that we’ve made good use of.

7. Measure quality throughout the process.

   • Tying all of our builds back to Sonarqube enabled us to keep track of quality, we also track metrics around the amount of time it takes to complete the process, ratios of successfull builds and deploys to failures, and a bunch of other stuff.

8. The Continuous Deployment process needs to be continuously improved.

   • We’re still working on the process. It’s important to not forget that there is always another issue we could be improving.

The Tools we chose

• Docker

  • Docker enables us to have superfast builds by building our applications in layers. By building these layers separately, when we build the application, we only have to build the application, rather than also having to build all of our dependencies and other bits and bobs.

• Rancher

  • We use Rancher for container orchestration and management, it enables us to keep a high level picture of what our applications look like somewhere easy to reach. It enables us to do a whole bunch of really cool things like load balancing, health checks and the bread and butter of container orchestration. Further, it also has a great repository of applications, stuff like load balancers, CTF stacks, container discovery tools, even a containerised version of the famous ELK stack. The capability to create your own catalog also exists, so once we’ve got all of our tools and services in to containers, we can spin up production ready software in no time flat, with all of the quality guarantees built in to our building and deployment pipelines. This is the part of our solution that I’m most excited about and I would recommend Rancher to anyone interested in container orchestration and management.

• Nexus

  • We use Sonatype Nexus 3 for a bunch of stuff. We have two instances of Nexus, one for integration ready blobs and one for deployment ready blobs. That means that all of our base docker images, sub-images, and layers we don’t want to send to prod live in our CI Nexus, and the only images that live in our CD instance of Nexus are images that are ready for deployment at a moments notice. We also use Nexus to mirror Maven Central and the NPM Registry in order to reduce our build times by removing as much network variance as possible. We also keep build dependencies in our CI Nexus, blobs like Servicemix archives, SoapUI archives and others.

• Bamboo

  • We use Bamboo to wire up our builds, tests and deploys. One thing that irks me about Bamboo is it’s lack of ability to verify a deployment and conduct system and smoke tests. That being said, it’s got an awesome build system and the a strong deploy system that allow us to tie any image running in production all the way back through the pipe, to the commit that triggered the build. That provides us with a great deal more visibility as to what code is where when compared with our old process.

• Bitbucket

  • Git and Bitbucket are the solid but silent performers. We use a Feature branching workflow with pull requests - we require that the only change to master is a pull request from dev, and code only gets in to dev via pull requests. Each request must have a minimum of two reviewers, no issues or tasks against them, and a passing bamboo build.

• SonarQube

  • Sonarqube enables us to track issues with our code, and break builds if quality gates aren’t met. It’s also a great tool to communicate the health of our code base to the rest of the business.

System Map

Here’s the system we built, end to end. It’s a bit busy but it is quite compact, and looking at it, I can’t see anything I would take away to make it simpler, which I think is a good thing. It’s as simple as it can be while still being powerful enough to deal with any deployment requirement we might have.

What value has the business derived from this project?

Applications that use our CD Pipeline gain the following benefits:

1. The application can be built and deployed to any arbitrary environment in less then two minutes in most cases, and we’ve yet to see a build and deployment take longer than four.
2. Batch sizes are smaller, so deploys are safer
3. Deploys can be rolled back in a single click, in the unlikely event of a failure

The business benefits derived from this then are:

• Vastly cheaper deployments, we’re saving about $800 every deployment on every project that uses this flow.
• Our time to production, where customers use our software, is under half an hour. The benefits of being to get feedback and iterate quickly provide us with an unfair advantage over the competition. I like unfair advantages.
• Software Quality is way up, which means less issues in production, less time spent supporting that software and less time spent maintaining that software.

I feel like that’s some pretty compelling stuff.

It was an awesome experience, and the first time I’ve spoken on technical and non-technical topics at an industry conference.

The talk I gave is available on Speakerdeck . I’ve also embedded it below:

I think that the one thing that I took away from Devops Days NZ 2016 was this.

It’s very easy to get wrapped up in your own problems in this industry. It’s very easy to feel like your problems are unique, new or otherwise unreproducible. Unless you’re Google, Netflix or of that ilk, this is very unlikely. You and I, we’re not so different. Maybe it’s health, maybe it’s media, maybe it’s any other industry. We’re all going through the same things, at different times. It’s important that we continue to work through these diverse issues as best we can, while knowing that someone out there has felt, is now feeling or will feel your pain.

You are not alone!

In the spirit of DevOps and all the baggage that that word contains and frees us from, let’s keep helping each other, let’s keep sharing, we’re a community of like minded people.

He spoke about how each time he became invested in a belief of something greater than himself, he was inevitably dissapointed. Each time he entered a different phase in his life, he believed in something new, and each time that belief was broken. He began to believe in doubt, he believed it might not be possible to believe in anything at all.

He compared his belief with ours.

There is a great hunger in our generation for purpose and meaning. Dan Pink describes it in his studies on human motivation, mastery, autonomy and purpose. That purpose is more and more, coming to be at odds with the society we share with other generations.

Casey realised that he was the dialysis for a country that needs a kidney transplant. His voice had stood in for those who had no voice themselves. This time the false saviour was Casey.

Some of us belief in the bible, or the Harvard Business Review. We hardly realise the human cost of our beliefs. We dare not question the founding bricks of our belief, lest the cracks at the bottom bring our whole facade crumbling down.

Why, with all the power we hold in our hands, are people suffering so?

He’s speaking about capitalism. He references the titans of our capitalist western world, Harvard, the New Yorker, ‘We see suffering as a necessary act of the capitalism that is our god’.

With his closing words, he says ‘And this doubt, it fuels me, it gives me hope that when our troubles overwhelm us, when the paths laid out for us seem to lead to our demise, when our healers bring no comfort to our wounds, it will not be our blind faith – no, it will be our humble doubt that shines a little light into the darkness of our lives and of our world and lets us raise our voice to whisper or to shout or to say simply, very simply, “There must be another way”.’

And he’s right. There must be a better way. There are hard questions we need to ask, that our politicians need to ask, because we live in a more prosperous time then any other throughout history, and yet deprivation is growing. The amount of inequality is increasing and more and more, a sense of resentment in those members of our global economy who are left behind is becoming apparent.

It’s that sense of resentment that people like Donald Trump are exploiting for their own benefit. It’s the reason why so many people in New Zealand rabidly hate John Key. People are being left behind, and becoming more desperate. Desperate people are in New Zealand are changing our political landscape. From attacks on MP electorate offices, to assaults on cabinet ministers.

We don’t have good answers for anything of this nature. That little light in the darkness needs to shine a bit brighter.

Fortunately we still have the passion, but unfortunately, our time has dried up.

We won’t be running Season 2 this year. Instead, Troy and I will be spinning off the software we wrote to manage the first season, and working on that to the point where it’s a viable product in and of itself. Our new tournament as a service will be called BattleStack - and we’re very excited to be working on it.

The Team would like to thank everyone who had input into Season 1, and our pre-season. Thank you to our sponsors, our game admins and the teams, you, our players. In particular, we want to thank the great folk at Bigpipe and Playtech. Without your support, our LAN Final would never have happened. Your support is what made it all work.

Thank you.

The awesomeness that was Season 1 is a perfect example of what all you likeminded people can do when you come together. We aim to make that ‘coming together’ scale.

So long and thanks for all the fish.

Alex

team@battlestack.io

Heather Armstrong, for those who do not know, is internet famous. I didn’t know that. I’m not her target market and of course, that’s okay. But what is she doing at webstock?

She’s telling us that she’s worried. Sure there’s humour, there’s some old war stories about pissing off sponsors, something about goats, and hairy vaginas - maybe I’m overthinking it, but I don’t think she is happy with the way the internet has become homogonised, white-breadified or, in Heather’s own words, “white privilege gone mad”.

I agree.

Like it matters what I think. But then, this is designed to be a critical analysis and you’ve read down this far, so let’s assume that it does matter.

At first I thought that Heather was speaking about how she loves the shit life throws at her. She loves talking about the ugly parts. The vomit filled car and car sick kids, the not having slept for two days on account of goddam slumber parties. At first it seemed that Heather simply wanted to tell us how satisfying it is being a whole human being, complete with all the flaws that humanity entails. I was a simpleton.

There’s a problem with social media these days.

It’s fucking fake man. That’s the crux of it. How many times have you not posted how awful your day was, because you didn’t want to be seen to be fishing for attention or sympathy? Believe me, if I’m posting about how crappy my day has been, there’s a pretty good chance I’m just venting, and don’t actually want any of your pity.

How many times on Snapchat or Instagram, Pinterest or Twitter, have you retaken the same photo forty times to get the light ‘just right’ or to wait for the perfect background tableau? #Instafilter #VSCOCAM #IveOnlyTypedThreeAndIAlreadyThinkLessOfMyself. Is that real? Is that raw? Is the rather mundane picture of your home made spag bol with a filter plasted over it, an accurate representation of your day? It may well be. How about the adorable raccoon account you follow? How about that wedding list? Are those ideas that you’re judging the most important day of your life against, a comparable wedding, with a comparable budget and are there people like yours attending?

How do you tell the difference?

That’s the point Heather is making. There are so many beautiful, natural and real things out there that we could be seeing, judging, loving. But we’re not. We’re wrapped up in what the Beebs said on twitter. We’re checking out Kim K on whatever godawful service she uses the most (probably all of them, actually?). This isn’t a new thing, it’s been a thing with magazines for a while now, hence models eating salad and water and starving themselves. Hence men stressing themselves out because they don’t look like He-Man (ps most girls think He-Man is too muscly so be cool guys we good. Or my wife is being kind to me. Shit). Kids are covering themselves in makeup because cleo or cosmo or whatever told them it was the right thing to do at the age of 8 (which is when most kids these days first see porn on the internet by the way - but that’s a different talk).

The rub is that the world (mostly) knows that these magazines are curated and unreal, that is, they misrepresent fundamental aspects of human nature. They lead us to believe that some highly idealised, highly managed and largely contrived set of circumstances, are real and normal and what we should all aspire to. And it’s wrong, dangerously so.

Heather knows this, she took great delight in pointing out the fakeness of it all. And she challenged us. I didn’t really realise until afterwards. There was this anecdote she told. She had a contract to write a thing about travelling with her kids. They didn’t want to be dragged out away from their lives, they resisted, and it put Heather in a position where she couldn’t write the bit. Because doing so required the involvement of her children even against their will. Now the children were part of her contract, before they had only ever been involved willingly. It felt like exploitation Heather said.

That begs the question, how far are we willing to create fake lives for the benefit of others? Surely it would be better for our own wellbeing if we were just honest that, yes, sometimes life is shitty and for no good reason.

Surely we would be better off as a society if we didn’t feel the need to ‘clean up’ the picture on the front page of whatever fitness / fashion magazine we hold so dear.

Of course we should, but money, but sex! But how will I prove that I’m doing better then $NEIGHBOR?

I feel like I’ve put a lot of words in Heather’s mouth, I want to be clear that this is my own interpretation of the message that I think she was sending. Communication is hard man.

It’s so hard that sometimes we have to fake it. That was okay in the past, because moderation and because an individual couldn’t influence the world back then in the way they can now.

Maybe in this modern age of instant communication and empty social media moments, we need to work a bit harder to be real, to be honest, but above all, to be human.

What I do know, is that I want to go back to webstock next year, regardless of whatever else is going on in my life at the time. These words are coming out like treacle right now, I don’t usually have a problem communicating like this.

Last night I said something that resonated with the people I was with. In a rare flash of brilliance, I said something that my friends were so affected by that they specifically mentioned it to others - “You have to hear this, it was amazing not shit 2deep5me interesting, come on and talk to Alex about it”. That’s not really something I’m used to

So what did I say? And more importantly, What did I learn?

What I said can wait until later, my exact words feel slippery, and at the edge of my vision right now. Rands said that writing helps teach how to order thoughts, and build opinions. He also said “Just hit publish” and he gave me this pen.

So here are a few things that I learned at Webstock:

1. The speakers of webstock, are at the top of their game technically. These are the gods of of our industry. People breaking new ground in user interaction, CSS, responsive design and content, the works. All these people, focused on the user, they focused on people. There were no java devs speaking at webstock this year (though I’m sure many of them knew java). This is important, I’ll address why it’s important soon.

2. The attendees, were people from Spark Ventures, Xero, Trademe, Digital Arts Network, and a huge amount of other companies. If the speakers were gods of the industry, the attendees were all minor deities, everyone who I spoke with was a leader in New Zealand - incredibly skilled developers, designers and others. What could we learn from the gods at webstock, that we couldn’t learn more easily through a technical blog? Why bother with it all?

3. The attendees were mainly technical people, but not a single technical talk was given. This initially confused and upset me, before I gained time and context around webstock. This is webstock’s 10th birthday, and that’s also important.

4. In isolation, none of the talks had anything to do with each other, there were several talks that, at the time, felt like missed opportunities. Harry Roberts talked about making cocktails. Michael Lopp talked about pens and writing. Askew One talked about graffiti and growing up poor in Auckland. I was gutted.

5. When viewed through the lens that I stumbled on during the after party, every talk I had previously been disappointed in, changed. Remarkably so. Askew didn’t talk about growing up in Auckland, he didn’t talk about the regional differences in graffiti. He said words about those things, but that’s not the meaning that he was communicating. He taught us about community. About a group of people creating something bigger then themselves.

Keavy avoided all talk of her work at Github, because she was teaching us about identity. About who we are and who we want to be, and how that can and should change at different stages of our lives, in response to different stimuli. She spoke about growth, not of our technical skills, but of our minds as people. She spoke about the messy growth of flawed human beings, who get hurt, get better, get sick and well again, and how we can help ourselves grow in the direction we value the most.

Debbie spoke on rejection. Here’s a giant in her industry, one of the finest design minds out there, and she’s telling us about how she got rejected from every postgrad school she applied to, about how she was ousted from industry organisations. But what she taught us was very different. She taught us about determination and doggedness. About refusing to be refused. About every failure in our lives being a defining factor in our eventual success.

Harry could have spoken about CSS architecture, about his work as a consultant, about literally any technical topic he had on his mind. Instead, he crowd sourced his talk. He showed us how to trust in others, he showed us that there is more to life then a nine to five. He showed us that amazing people are literally everywhere, and all you have to do to see that is to flick a tweet out into the ether.

Casey Gerald. I think I had began to link up these threads by the point that Casey spoke, that or he was the one who forced me to drag the threads and weave them in to rope. Of all the people I have ever heard speak, he is the most memorable. He was the last speaker at webstock and by far the most impactful. He’s better then Petraeus, Obama, he’s better then any actor or actress in any movie I’ve ever seen. Every word held meaning to him, every moment, considered. It’s the most surreal situation I’ve ever been in. It was just.. right. I have never been as certain of anything in my life. But what he talked to us about, was doubt.

He talked about his upbringing, his education and his work, he detailed how each stage in his life was renewed by an earth shattering break in his beliefs. He taught us about doubt, about how examining a crack in our beliefs could shake the foundations about who we are as individuals, and who we are as a collection - whether that collection is a community, a nation, race or people. How could we not question everything? We live in a world where there is injustice, inequality and hate - but we equally live in a world where amazingly talented people care. Where people who can do something, do. Casey challenged us all to evaluate what we were doing was helping as many people as we could. He dedicated his professional life to helping people until he had the realisation that he couldn’t save everyone, then he gave away everything he had built, so that we could all save each other. He leads by example.

So what gives?

Why should anybody give a shit and what epiphany of yours was it, that affected people the way it did?

The point of webstock this year, wasn’t to teach us new technical skills. It wasn’t to help us get ahead of the pack or beat the competition. The goals of webstock 2016 felt much loftier then that. Webstock 2016 aimed for nothing less then to fundamentally shift the way that we, the attendees, interacted with the world. We had the best of the best, the gods of our industry; people of such astounding intellectual brilliance that we looked up to them as personal heroes, just.. being human. Being good humans. Good humans talking about developing the traits that we want to see reflected in our world. These people helped us see that as an industry, we are in a position to change our own futures. Whether that’s fighting global surveillance, addressing poverty and inequality, challenging and changing rape culture, domestic and sexual violence or just helping people be happier, healthier humans. It’s incredibly humbling to think that the most valuable contribution these people made to our lives was to help us think differently. A personality request rather than a pull request.

So what exactly did I say? I don’t know, but it went something like this:

What they taught us transcends any one technology, methodology or practice. These speakers are specialists in technology, yes, but more then that, they are world leaders in interaction. They showed us new ways of interacting with people, new ways of thinking about how things interact with people. Any technical subject would have been mundane by comparison amongst talks that taught about no less then a fundamental shift in our own psyches.

That sounds shit, and it doesn’t capture what I said or the inebriated eloquence of the thought I put out there. But it’s a start. And if there’s one thing I’ve learned this week, it’s that starting is the hardest part. It’s also the most worthwhile.

So without Further ado, here’s what we’re running at the moment.

I’ll go through our components technology by technology:

Most importantly, Docker

We couldn’t do what we wanted to do with Overtime’s CI / CD without docker. Initially I created docker-compose containers for instances of Docker Registry, Nginx, and MongoDB and our Web App. The plan was to containerise those components because it would allow us to scale up instances of our web app and MongoDB in case our load got crazy high. An ambitious design requirement, but much better for the long run. In fact nearly every design decision we’ve made technologically has been focused on “What will make our lives easier in the long term”. We do this voluntarily so making money immediately and as quickly as possible isn’t such a huge issue for us! It’s nice.

We had a bunch of technical issues with Nginx not liking being containerised and not linking to our other containers properly. That resulted in us shifting it to the VPS itself and using it for reverse proxy and routing, it’s working pretty nicely so far.

We run separate production and test environments. Local builds are automatically built and dockerised on commit, are automatically deployed to our test environment with 0 loss of service. When we’re ready to go to prod, we just retag the docker image in question as prod rather than test. Docker picks up that there is a new image available and redeploys in the same way as our test environment, meaning we also get 0 down time. We still plan our deployment windows for early in the morning just in case something breaks but the process seems pretty solid so far.

Our Web App

Overtime uses a Java 8 back end with an Angular front end. Once the application is complete, players will be able to register themselves and their teams, sign up for tournaments, track points, rankings tables identities, and communicate with organisers and other teams. We have a dedicated slack team for overtime and we’re planning on our players being automatically enrolled into slack on sign up. I also want the enrollment process to add them in to relevant channels (they might get a private team channel and enrollment into open game and interest channels) - but we’re still thinking about how that would work!

We’re using MongoDB because we really like it’s object paradigm, it’ll make it easier for us to manage our data long term.

Speaking of building:

We use Bamboo for our CI/CD work, initially we used Jenkins but found it unreliable, prone to random failures and difficult to set up, maintain and extend. Bamboo is a much more user friendly solution. We had set up our build server as an additional docker container on the first VPS but thinking about it, we wanted to ensure that development work could never impact production environments. Because of the size of our VPS it was possible that our build container could cause production issues by hogging up resources while building things. An edge case but with the focus on the long term we decided on separating that out on to it’s own VPS with its own resources.

Project Management

We use Taiga.io for project management. It has the option for sprint or kanban set ups, it’s a hosted solution and it’s free, which fits our budget! Taiga is also open source which means that we can take it, self-host and extend it should we ever need to provided we comply with the licence, which is another bonus.

Wrap Up

That’s all the detail I’ll go in to for now. I hope this helped you, if you want any more detail or you’d like help with your own projects, let me know, I’d love to see how I can help!

I’ve been on holiday for two weeks! It’s been pretty good.

I spent a week in Ohakune, in the central Plateau of the North Island of Naw Zealand and another week in Russell, much further north. It was awesome to get away from Auckland, but I’m ready to go home.

I have spent my time organising my reading list for the upcoming year (scheduled for reading are gems such as Code Complete, Continuous Delivery, The Fundamentals of Security and The Mythical Man Month). I’m excited, I’ve got about 60 books lined up for the year and I can’t wait to get stuck in.

The Christie Marceau Charitable Trust

I’ve also spent a good deal of time helping out with the trust. The woman who runs it is a good friend of my mother in law. The trust needed a refresh of their website and to consolidate the digital presence they had.

They were paying $300 a year for a bunch of services they didn’t need (part of the package they had gave them 50 databases! 50 databases and one website

• what a hilarious way of making it seem like your product represents value for money to those who don’t know any better. Honestly the state of web hosting in New Zealand makes me feel angry. So many people who don’t know better are getting fleeced by these companies who, at the end of the day, provide a poor service simply because competition in NZ is so abysmal).

/rant

Anyway, I rewrote the trust website into an angular site with a bunch of content, realised it was as ugly as sin and enlisted the help of a talented designer named Walt. He helped me out with the design, I cancelled the trust’s old web services package and the new setup is super simple. I ditched Angular, hosted the page on github pages (TY GITHUB) and now the trust only needs to pay for the domain name every 2 years. It’s a solution much better suited to the actual needs of the trust and I’m glad to have been able to tailor a solution for them. It’s a timely reminder that what is simple for people in the tech industry often isn’t for people outside the industry. A timely reminder for me to stay humble and focus on how I can help people rather than how I can make as much cash as quickly as possible and screw the needs of the person I’m representing (looking at you Free Parking ಠ_ಠ). The new website is fairly basic at the moment but it’s functional and thanks to Walt, it look good. I’ll expand on it content wise throughout the year, I hope to post fairly regular updates on it though that will depend on the trust having news to share!

Overtime Tech Talk

I’ve taken some time out to draft a post and presentation on Overtime and how exactly our technology fits together, it’s still in the works but for those that care, I haven’t forgotten! I promise!

That’s it for now, time to hit the beach!

The past month has been crazy.

In the past month, I’ve started a new role, my son has started crawling, I’ve helped launch the second season of Overtime on a brand new technical stack, they only thing that hasn’t changed is this blog, I’ve been neglecting it. Work has slowed down a bit before christmas, so now seems like a good time to post an update.

Leaving Spark Ventures

I left Spark Ventures after working there for a year. They supported me in the first full time role as a software developer that I’ve ever had, I’m extremely grateful for the opportunities they gave me, and I’ll miss the team and the work. I left on great terms and (if it’s in the cards) I look forward to returning in a more senior role. Before I left, my team was working on continuous integration and deployment. We successfully transitioned Bigpipe from a completely manual deployment process to an automatic one. It was a really enjoyable task, and once it was complete, I wanted to keep doing that kind of work.

Enter Healthlink, stage left.

I was made aware of an opportunity at Healthlink to continue doing work like the work I did for Bigpipe. The situation here at healthlink makes the Bigpipe automation simple! Healthlink runs a product that enables health practitioners to send documents - referrals, letters, medical certificates, test results and so on - digitally between providers. It’s the reason that you can get a non-funded drug approved by Pharmac in three days rather than three weeks. It’s behind your rural doctor getting results back from that specialist lab in the big city as soon as the results are done - without having to wait for the rural post service to deliver the mail.

It’s an complex system of java applications, web servers, auth servers, databases and APIs that have got loads of tightly coupled moving parts. I’m helping them work through that system with a view to achieving CI/CD - completing this process will hopefully reduce the degree of coupling, consolidate technologies and generally refresh the tech too. It’s the biggest job I’ve ever attempted, and I’m glad that I’ll be working alongside some incredibly clever people - all of whom will be able to teach me a great deal.

Overtime Season 2

Overtime season 2 has launched!

We’ve completely rebuilt out tech stack! There’ll be another post coming with the specifics on what we did and how we did it, as well as some challenges we had to overcome. We’re looking at returning to the NZ eSports scene bigger and better then ever before, and I think we’ll start to see some traction this season. We’re more organised, more experienced and have better technologies behind us. The team is expanding - more people working on more things mean we can just do.. more!

Watch that space, season 2 is going to be excellent!

Toby has started crawling!

I’m pretty proud of that little guy. He’s ahead of schedule for all of his developmental milestones, he was born on the wrong end of the scales for average head size, body size, body weight and a bunch of other stuff. At 8 months old, he’s now in the 97th percentile for head size (aka big ol’ brain) and is above the average for his other growth indicators. My wife is doing a great job being a mum while I have to leave for work every day. I’m very proud of them both.

Things are looking pretty positive.

I’m in the proess of writing a whole bunch of posts, and will be hopefully publishing a bit over christmas. TTYL. Beer to drink.

That’s a pretty huge productivity increase

Especially given that it was two juniors and two seniors across three months that did this work.

We’re not done yet, we’ve still got some UAT and final bits and pieces to deal with, but I’m proud to say that we’re mostly there.

Here’s a basic run down of how we did it:

We chose Atlassian’s Bamboo as our general purpose task runner. It’s the backbone of our process. We chose it because it’s got a nice interface, awesome integration with Bitbucket (which all of our repos are hosted on) as well as Jira and Confluence.

It can provide us with automatically generated information about the issues addressed by a deployment, link back to repos if we need to sanity check source code and a bunch of other cool stuff. We’ve also added webhooks to our deployment channel within Slack, so Bamboo posts alerts to that channel when a deployment completes.

We’re stuck with a bunch of technologies that aren’t being used correctly (Like using Puppet to manage individual machines rather than types of machines) and Bamboo is going to give us freedom to swap out discrete pieces of the process as and when we need.

We’ve got a bunch of scripts and SSH tasks that reach out to our repos, check file versions, run puppet agents (yes, manually running rather than every n minutes), stop queues, dump databases for backup purposes, start queues and all sorts of other nebulous tasks.

The end result is that to build a venture project, all a developer needs to do is commit code. To cut a release they need to select a branch to build. To deploy to a dev, test or staging environment they need to select a build result and click deploy, same deal for pre-prod and prod (with a few additional caveats).

The great thing is, the teams are onboard with it.

This is a huge amount of disruption to the way 80% of our team does business. It affects developers, testers, BAs and product owners. Without exception, everyone that I’ve talked to is pumped. It’s a credit to the guys here that they aren’t stuck in a process but are always looking to improve. It makes me happy.

I’m losing faith in the design of my website. It looks dated. I’m not really sure what to do with it other then give it an overhaul. But that requires coming up with a new look and feel. It requires implementing that. But muh effort, Muh time constraints and other such excuses of the weak willed.

I’m going to learn about design.

Rather then just minimally modifying a template, I’m going to look at every piece of this website and give it some love and attention. It’s been quite neglected.

I want to focus on creating something that is minimal, contemporary and clean. I like white space, I like strong borders and well defined blocks of content. Turning that into an actual design will be interesting! Until I know more about what I want to achieve and how to get there, I might have to be content with making a few structural changes and a few CSS tweaks here and there.

Project Updates are important.

I need to go through the groups within my site and update them in terms of content as well as design. I’ve done a bit of work, had a bit of a play with different technologies, as well as submitting some interesting university assignments. I need to throw that work up on to the projects section so it can be consumed!

My skills and Experiences have also changed.. slightly

I should update that section to reflect the work I’ve been doing recently at Spark Ventures around continuous integration and deployments. It’s technically interesting, requires technical nouse, involves communicating with dev teams, creating and changing work flows and managing the expectations of the product teams, development teams and bigger fish higher up in the Spark Ventures food chain. It’s been fun.

With the publication of this post, I’ve changed the font from Junction Regular to San Francisco - because I love the OS X El Capitan font that much.

What a difference that makes:

Let’s be clear right at the start, I have used maybe 15% ~ 20% at best, of the knowledge I learned at University. Most surprising of all is that most of what I have used, came from a stage one course. Yeah that course in HTML that everybody turns their noses up at because it’s for plebians who can’t into C? Take it. You’ll earn dollars with that course.

Speaking of courses, I’m in my second year of Uni, when I started with Summer of Tech I was the second semester of my first year, by the time the program wound down and internship offers were out I had completed my third semester - which brings me up to date as of writing this (I’m not taking any summer school papers - I’m not smart or beautiful enough to get away with that).

I’m doing a double major in Geography and Computer Science, and for those of you at the start of your studies, I would recommend picking up a second major, it gives your more flexibility in your degree, looks better on a CV and to be honest, it lets you avoid the courses in each school that don’t interest you or have bad reps for being poorly run. My degree consists of courses that I 100% love and am interested in, which makes it a lot easier to learn the content. Don’t hate your study, change it.

For those that want the nitty gritty of how useful each particular course has been, here’s a breakdown for you. Please note that I’m trying to keep it institution agnostic, so people who aren’t at the same place as me can still understand the topics I’ve covered and hopefully still get some value out of this post.

On the CompSci side of my degree, I’ve studied all the level one papers available, they are pretty generic so they don’t get named individually - they contained the basic theories of CompSci, the history of the field, an introduction to Java (though I understand they have now changed from Java to Python) and an introduction to data structures.

At stage two, so far I’ve taken courses in Discrete Mathematics (I was tricked into it, the course code said CS but should have been MATH), Algorithms and Data Structures, Software Construction, and Low Level Programming.

Software construction focussed on Java GUIS and threading, which haven’t been so useful for me here thus far, there was a small module on testing and a small module on version control though, and both of those were invaluable. Many people turn their noses up at testing, but it’s actually one of the most critical aspects of shipping software. If your code doesn’t work, you don’t (or shouldn’t) ship and you don’t get paid (Except if you’re a Triple A Game Publisher - I’m looking at you BF4 / AC:Unity).

Low level programming covered computing from Transistors up through to the C programming language. It’s a useful course in that it gave me a background in how computers actually physically compute, and therefore how to make things as efficient as possible, and why that’s important.

Algorithms and Data structures is a hard course, but also valuable in it’s own way. the knowledge there is the kind of knowledge you forget you need, and then you look at your code one day and think why is this so buggy and horrible and slow? Oh wait it’s because I somehow have made a triply nested loop where each iteration of each loop calls a recursive function. That’s probably hyperbole. But I am certainly much more aware of the way I structure code and solve problems now. So that’s something. I also learned search, I haven’t used it for work yet, but in one of the games I’m working on in my spare time, I use search, so that stuff is good to know.

As I alluded to earlier, discrete mathmatics, although billed and coded as a CompSci course, was actually

taught by math staff and was a maths course in disguise. It’s one of those courses where you don’t notice yourself using it until you find yourself trying to prove that some graph has some property and therefore is a better choice as a data structure than some other structure. I’m loathe to admit that it was a decent course because I don’t like, nor am I good at math. I’m probably in the wrong industry, I know.

Learn a version control system and become very familliar with it.

It’s an unwritten prerequisite that you know Git or some other version control system before you get into the workforce. If you don’t know what I’m talking about, at Ventures here we use Git . I also ended up learning Bash . Linux users you should have no issue with this, OS X also has bash. Windows users, it’s a bit wierd at first but once you get used to it, it makes life a lot easier (I actually find that I can do things in bash via command line faster then I can do things using a GUI now.)

Take the time to do your own projects, it’s a great way to learn something new. It was probably my dabbling in Javascript and html - and the projects I did - rather than my somewhat incomplete knowledge of University level Computer Science that helped me more in getting this position

Don’t forget to go outside. I’m real bad for that.

=================================

I have loved technology ever since I was a wee nipper. I confused a lot of people when I joined the Army after college but that decision was key (more on that another time though). I left the Army in time to enroll in Semester Two 2013 at the University of Auckland. I sit here now, on the top floor of Spark City in Auckland, and I feel very, very fortunate.

I’m Alex, an intern Software Developer for Spark Ventures over the Summer of 2014 (and hopefully after that also). It’s a tough job breaking into a new industry, but worry not, I’m going to tell you how I did it, and how you can do it too.

The work here at Spark is awesome, just this morning I designed and implemented a web page that leverages social media to increase engagement with customers. I’ve dabbled in web stuff before but this is an actual product that will may go live at some stage, it’s a cool feeling. A fellow intern is working on automating some work processes we have here, to save time and tears (a lot of tears in my case) and this is only our second week. I’m looking forward to the rest of summer and the sweet projects we’ll be working on.

I got involved in an excellent program called Summer of Tech , they run boot camps and workshops on all sorts of stuff that industry needs but Uni doesn’t teach you. They run meet and greets and interviews with companies, they organised a day long hack-fest where teams of students get together and work on projects to win prizes and impress industry reps, it’s a great program. If you are in Auckland or Wellington, get involved ASAP.

It’s not the only way, but they certainly took a lot of the leg work out of the equation for me. Summer of Tech made it about my skills and experiences, and how I interacted with companies, rather then how good I am at cold calling or finding opportunities. Summer of Tech put the opportunities in front of me, all I had to to was grab them.

Plenty of big companies offer internships, those not involved in Summer of Tech often have their own programs, I went to a few of those, you should too. Friends of mine have got internships with Deloitte, PwC and the Wynyard Group, they did it through company recruitment events, not Summer of Tech.

Put yourself out there, if you see an opportunity that isn’t quite what you were after, who cares? Take it anyway. Learn something new. Apply for everything you can, be greedy, say yes. People remember those positive types who say yes to everything. Managers want to look good right? Well managers will remember you if they think you’ll make them look good, and if you make them look good, they’ll remember that and repay you the kindness.

Work hard, strive for excellence, again, make your manager look good, or make that potential manager think you’ll do such great stuff that you’ll both look good.

Know your field. It’s hard to make your manager look good if you don’t know how to do your job. You want a role in the IT industry, you need to know about the tools and procedures that get used in the industry, it’s that simple.

Be a decent human being. Arrogance, Rudeness, Idleness, these traits will make you stand out for the wrong reasons. Be mindful of that. I’ve spoken to people who feel that if they have an 8 or 9 point GPA, industry should be seeking them out, not them seeking out industry. Grades are important, but it’s more important to be able to function in a team environment. You need not be party central, you need not be a superheroic extrovert and the center of attention (I’m certainly none of those things!) but you do need to be able to form meaningful relationships. You need to be able to leave the right impressions on people, for the right reasons. So when you meet people, wear deodorant or anti-perspirant. Shower. Clean your teeth. Dress appropriately. All those good things mum and dad told you.

Your ability to form relationships and communicate, and your ability to learn new skills will get you a job. Taking your waifu pillow (Dakimakura?) to the interview will not. I’m not saying don’t be into that stuff, what you do at home is neither my business nor an employers’. All I’m saying is be professional while meeting professionals.

Seriously guys, I can’t stress this enough. You can have a ridiculous GPA, but if you can’t communicate or form relationships, it’s going to make your life a lot harder then it needs to be (Summer of Tech does workshops on soft skills like interviewing and meeting people by the way). If you take nothing else away from this post, take the above two paragraphs.

TL;DR, How do I into internships
1 Join Summer of Tech or go to Company Recruiting Events
2 Be cool, be good at what you do.
3 Put your hand up. Say yes to every opportunity that comes your way, the worst that can happen is nothing.
4 Follow up with recruiters
5 ????
6 Profit (Literally, they pay you to do what you love)

I got where I am today with hard work, a bit of stubbornness and some luck. I can’t implement Djikstra’s algorithm in assembly language, but I can interact with people -ish. You can too. The results are always worth it and there is never a better time to start then now. If you have any questions you feel free to hit me up on twitter (@4lexNZ ) or this website, either by email on the main page, or by dropping me a comment below.

My name is Alex. I’ve no idea if anybody will read this, it’s more for my own sanity anyway so that’s fine!

I’m a student at the University of Auckland, currently working over summer as an intern for Spark Ventures. I’m loving being back in a real job. Don’t get me wrong, University is great, but the amount of time I wasted every day sleeping in until 11am because I didn’t have class until noon, was ridiculous.

I hope to populate this blog with revision notes from my classes, once classes start back up, as well as passing comment on anything and everything, as and when I see fit.

This is the first post so I will end it here, with this sweet picture of a a place near and dear to my heart.

This time I’m going to be looking at it from the Employer perspective. I’ve been handling Spark Venture’s Summer of Tech efforts this year as well as dealing with sponsorship stuff, running bootcamps and of course, running the Hackfest (that we held at the awesome Spark City Conference center)

The Meet and Greet is competitive. Students want to impress the best employers, and likewise, employers want to imprint themselves on the minds of students as “The place to be”.

Last year, I would have found it useful to know my way around the process, in the end I just drank beer and talked shit, and that was good enough - depending on who you ask :P

Firstly - Talk to everyone. Talk to every single employer in the room, regardless of whether or not you want a job with them. For one, it’s great practice. Communication sklls are the API that all of your other, more technical skills are exposed via. You can’t expect employers to spend money on you (onboarding is expensive!) without them being confident that you have the skills needed. If they can’t see or verify those skills, you may as well not have them. I beat students last year who were a lot more talented, hardworking and conscientious then me, because I could more readily communicate. It’s not fair, but it’s how the world works (there are always exceptions mind you).

Secondly - Don’t get too drunk. If you’re as fond of the gin as I, it might pay to watch your intake. It’s exciting, it’s fast paced, it’s a competition. It’s easy to lose track of the little things (by that I mean, it’s easy to lose track of everything that isn’t related to talking to employers). If you’re the type of person that can’t stretch a drink out over a few hours, consider banning yourself from it until the end of the night. Personally, I thought of it as a reward system, Every time I did a circuit of the employers present, after having had meaningful 5m+ long conversations with them, I would reward myself with one low alcohol content beer. Another way to think of it is like this, if you’re drinking enough to feel more then a good buzz, your lips are spending too much time on the end of a bottle, and not enough time on the end of a conversation.

TL:DR - Be cool, manage your intake, don’t be that guy. You know the one.

Finally, enjoy it. When dealing directly with people who could give you a job, it’s easy to feel the pressure. Try to focus on having great conversations, and enjoy the time with your fellow students, and employers who are passionate about the industry they are in. Without fail, every single employee in that room is there because they want to be, because they love what they do, love the industry they work in and love what Summer of Tech does. Enjoy yourself, the best conversations happen when you’re happy and comfortable, not when you’re forcing yourself to say words for the sake of somebody else. It’s about you. Own it, enjoy it. I can’t stress that point enough.

Gulp is what I’m using for builds, the output of gulp’s build process is piped into a folder that I’ve set up as a nested github profile. BrowserSync handles all of my testing and content iteration, it’s amazing. To get a post onto the live site or make some other change, all I have to do it write it up, check it looks right using BrowserSync and then git commit -am "Of course with a sweet commit message" from my prod folder. Yes there are extra steps that I’ve introduced, but that allows me to make big changes with multiple commits, iterate and push to test as much as I like, without the risk of omnishambling my live site. It’s pretty cool.

Technical things aside, my boy Toby is nearly 5 months old. Time flies. I’m working full time at Ventures, it’s awesome. Super glad that I did the Summer of Tech programme when I did, else I’d still be working at the liquor store. That would be a grim existence indeed.

I am technically still at Uni. The longer I work in the tech industry though, the less relevant Uni becomes and thus the more difficult it becomes to stay engaged in my studies - especially when still no course I’ve done past CS111G has actually been useful for work. It’s maddening.

It could be a lot worse though, my amazing son and beautiful wife are keeping me honest, in an industry I love. First World Problems indeed

That’s always been a pretty cool thing for me, but when my own little one was born it made things quite a bit more important. Tobias was born premature due to a rare condition my wife had. He narrowly avoided the neo-natal intensive care unit (a few days earlier or a few tens of grams less and he would have gotten a sweet incubator)

We got results back from his umbilical cord and placenta analysis - turns out there was a blood clot in the cord. I imagine if the docs new that, he would have been whipped out via c-section the second we presented to the hospital. He should have been stillborn, all things considered, Laura could have died if a part of the clot broke off and got into her system. Fucking unreal. We’re very lucky. Miraculously so. The odds were super against us.

Which is why now, more then ever, I’m motivated to ignore a lot of baggage and more than a little bit of fear, in order to crack on and get stuck with big needles. Because people need blood, my wife and child nearly did, others sure as hell do. During her hospital stay she wasn’t the sickest person on the ward, nor was Toby.

Shit’s important yo. Go donate. Each donation could save the lives of 3 people. What’s a bit of fear and discomfort compared with the lives of 3 people?

The days are getting longer but the weeks are getting shorter!
I’ve been neglecting this platform, but haven’t forgotten about it.
At Uni, exams times are approaching, I’ll be posting all of my revision notes on the blog - to keep me honest and keep everything searchable.

In the time between posts I’ve been crazy busy. Juggling Uni with work and having a son, while still doing pet projects for my own learning. A while back a few friends and I started something called overtime, It’s a very exciting project - www.overtime.nz. I also joined an ARMA 3 Clan called SOCOMD, I’m rewriting the website and blog they use on my own time, and they’re very pleased with what I’ve done so far. Check it out at www.socomd.azurewebsites.net. Another very cool project.

I’ve been doing what I can to get to uni and lectures, but frankly I haven’t been very successful in that regard. I’m handing in assignments on time and have passed all my tests and stuff so far, so it’s not an unsalvageable semester, but it is a very tight wire that i’m walking on. With luck and effort I’ll do well, but the more I attend uni, the less I feel like it’s actually helping me.

I’m still working at Spark Ventures, I’m also involved with Summer of Tech this year. Both are awesome opportunities for me in regards to career prospects.

The flipside of having a child now is that I’ll be seeking full time work in, around or slightly before August. I’m undecided if I’ll stay with Spark or if I’ll throw in with Summer of Tech, either options are really good.

Thats why Uni is such a conundrum for me. I want to get as much done as I can before that August cut off, but by the same token, I’ve got a job, every week of full time uni over full time work represents significant loss of earnings for me, at a time where I want to be earning as much for my boy as I can.

Compounding that is the fact that I feel like I’ve lost the faith with the CS department here. The stuff I’m learning right now just doesn’t feel relevant, the most useful paper I’ve done so far at Uni is still a stage 1 paper that taught basic html and css. I can’t help but feel like the purpose of going to uni was to get a job, and now that I’ve done that, why am I still giving these people money for what is essentially learnings that are irrelevant at best and outdated at worst.

I don’t know.

I’ve got some stuff to work through I think. I’ll be glad to see the end of full time study later this year. Of course once I start working full time, I’ll study part time and get my degree done eventually. But is there any reason to let it weigh on my mind and my time as heavily as it does right now?

I don’t know. I guess time will tell.

Here’s the situation.

Last Friday, my wife Laura and I found out she is 34 weeks pregnant with a potentially life threatening complication, forcing her to remain in Hospital.

We have been overwhelmed with the generosity of our family and friends, we are truly grateful for all the love and support we have received thus far.

I have been meaning to write up all my notes and use this blog for revision. I still intend to do that. I have been attending lectures but unfortunately am so time poor apart from that, that I have loads of text files that need formatting, media added and additional detail before I can upload them here. I still intend to do that, but it will take time I don’t have now. Hopefully I can fully catch up during the mid semester break.

I’ve made notes on my github projects reflecting the current status of the projects. Hopefully I can get back to them at some stage. Funnily enough there is a lot of work preparing to have a first child with three weeks notice. Again, once things settle down I hope to get back to those projects.

I want to thank everybody who reads this. I’ve had a pretty steady amount of visitors, almost 600 per month for the past months. It means a lot to me that people are reading, and hopefully enjoying what I have written, even if my original intention was to use this solely for revision purposes.

I will attempt to post whenever I can, time and content permitting.

Cheers

Alex

I also bought a great book today with a bunch of coding exercises in it. I might again take time off the scrambler in the future to work through those programs, as they are waaay more likely to help me in interviews than that program (at least when it comes to answering technical questions).

Also, started reading ‘Cracking the Code Interview’ - this book makes me appreciate how little in know about interviewing! I’ve got a lot of work to do if I want to bum rush the bigger software firms!

I never really got hash tables. Like truly understood them. I could see the purpose but where was the justification for them being everywhere?  Fortunately Uni is exactly the time and place to be smashed down for having silly thoughts like that! Hashing is used for a whole lot of really useful, really cool stuff. Or hash functions rather

Passwords - think about login credentials can be stored securely on a server. Your password to neopets.com is a closely guarded secret, but how is it kept secure? Before I go any further, it’s important to note that the hash functions I’m talking about now, are not the same as the hash functions used in hash tables. A hash table can search, insert or delete keys in  O(1)  in the average case and  O(n)  (meaning that most of the time, the time it takes to find something in a hash table is directly proportional to the amount of things you have in the hash table). A hash function for a table is made for speed, not security.

So please don’t use your (x mod y) hash function to store or encrypt passwords.

There are all sorts of different cryptographic hash functions, that but they should all do the same thing. Ideally they:

• Can easily make a hash value for any given message
• Manipulate a message in such a way that it’s hard to generate a message just from the hash value
• Make it difficult to modify the message without also modifying the hash value
• Make it incredibly unlikely that two different messages evaluate to the same hash (for reasons that should hopefully be obvious!)

This is all in an ideal world, in reality, sometimes you can’t use an ideal function, there are always tradeoffs to be made in terms of speed vs security etc, and there are a bunch of ways that such schemes can be broken.

Wikipedia  quotes three such angles:

• Pre Image Resistance
• Second Pre Image Resistance and
• Collision Resistance

Actually I have to leave it there, I don’t understand enough about the different angles yet.

Note to self, Don’t forget to continue this series.

In the mean time, read a bunch of wikipedia!

Be patient when changing domain name. This site was down for most of the day today because I was an impatient prick.

Be patient!

Every single day, I get out of bed with a passion for helping people be their best selves. A passion for making life easier, more inclusive and frictionless. I do that by growing and serving diverse, empowered teams of passionate humans, rallied around a cause.

Having spent the last 15 years learning how to parse big meaty problems into smaller issues in order to solve them with technology, I’ve honed in on the type of work I love. I write about technology, product development and other things when I do write. With two kids + wife, university and full time work, life always seems to get in the way.

Awards

• Winner, Emerging Young ICT Leader of the Year (2023)

At LIC I repaired substantial rifts between departments where those relationships later drove substantial technical transformation in areas of substantial risk and complexity. At FarmIQ I rebuilt the architecture function transitioning from architecture antagonistic to engineers to a practice focused on helping engineers do what they do best.

These significant cultural transformations drove technical success in both businesses.

At LIC I created new operating model concepts and ways of working that enabled business success not previously possible - my teams delivered a brand new product to market (Smart Wearables) in eight weeks, where previously the business could only ever deliver iterations on existing software in 10 weeks due to being shackled to a 10 week SAFE release train.

At FarmIQ the cultural changes I brought made it safe for engineers to work on the technical health of the product while introducing supporting capabilities that helped engineers deliver more change in six months then they had the previous year.

The technical success I delivered downstream of cultural success led to significant business success in the form of profit and revenue growth at LIC. FarmIQ made me redundant soon after my achievements there due to a failed capital raise - I was unable to stay long enough to observe results there.

For this work I was awarded the Emerging Young ICT Leader of the Year at the 2023 CIO Awards.

Projects

Professional

• Datapay - There is a good chance you've been paid by this software at some point in your life!
• FarmIQ - Software to help convert dry matter into milk, beef, lamb and wool as efficiently as possible
• MINDA Live, Unnamed Digital Platform - Agritech
• bnz.co.nz - Banking, Fintech
• Healthlink - Healthcare, Distributed Messaging Systems, Developer Experience
• Morepork.nz - eCommerce, Security
• Bigpipe - ISP / Telco

Personal

• Valuable - Decision Making, SaaS Web Applications
• Voluntari.ly - Open Source, Social Good

Long Talks

• DevOps Days Wellington - Health is hard // Slides

• Summer of Tech Bootcamp - DevOps: The Good Parts

• Junior Dev Meetup - Deliberate, Continuous Career Progression

Lightning Talks

• Full Stack Day Auckland - The Role of a Software Developer

I’ve delivered cultural and technological change both ways: big bang greenfield builds and gradual, continuous improvement. I know when a business needs which.

I have found through practice that the happiness of your users rarely diverges from the happiness of your technical staff.