Category: Toolkit

Wardley Maps

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

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

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

Wardley Map Example

Links

Architecture Decision Record

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

What is an architecture decision record?

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

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

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

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

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

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

Abbreviations:

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

How to start using ADRs

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

Decision identification:

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

Decision making:

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

Decision enactment and enforcement:

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

Decision sharing (optional):

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

Decision documentation:

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

Decision guidance:

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

How to start using ADRs with tools

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

For example:

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

How to start using ADRs with git

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

Create a directory for ADR files:

$ mkdir adr

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

$ vi database.txt

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

Commit the ADR to your git repo.

ADR file name conventions

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

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

Examples:

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

Our file name convention:

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

Suggestions for writing good ADRs

Characteristics of a good ADR:

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

Characteristics of a good context in an ADR:

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

Characteristics of good Consequences in an ADR::

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

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

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

ADR example templates

ADR example templates that we have collected on the net:

For more information

Introduction:

Templates:

In-depth:

Tools:

Examples:

See also:

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

Technical Debt

Software systems are prone to the build up of cruft – deficiencies in internal quality that make it harder than it would ideally be to modify and extend the system further. Technical Debt is a metaphor, coined by Ward Cunningham, that frames how to think about dealing with this cruft, thinking of it like a financial debt. The extra effort that it takes to add new features is the interest paid on the debt.

Martins Fowlers description of Technical Debt

The metaphor of debt is sometimes used to justify neglecting internal quality. The argument is that it takes time and effort to stop cruft from building up. If there new features that are needed urgently, then perhaps it’s best to take on the debt, accepting that this debt will have to be managed in the future.

The danger here is that most of the time this analysis isn’t done well. Cruft has a quick impact, slowing down the very new features that are needed quickly. Teams who do this end up maxing out all their credit cards, but still delivering later than they would have done had they put the effort into higher internal quality. Here the metaphor often leads people astray, as the dynamics don’t really match those for financial loans. Taking on debt to speed delivery only works if you stay below the design payoff line of the Design Stamina Hypothesis, and teams hit that line in weeks rather than months.

There are regular debates whether different kinds of cruft should be considered as debt or not. I found it useful to think about whether the debt is acquired deliberately and whether it is prudent or reckless – leading me to the Technical Debt Quadrant.

Technical Debt Quadrant

From https://martinfowler.com/bliki/TechnicalDebt.html.

See also The Human Cost of Technical Debt – the human side of the problem.  And, make no mistake — in business, all human problems are also business problems,viewed with a wide enough lens.  Unhappy humans are unhappy workers, and unhappy workers are less productive.  Yet, this angle of technical debt is seldom discussed, in my experience.

  • Unpleasant Work
  • Team Infighting
  • Atrophied Skills
  • The Hidden Business Cost: Turnover and Attrition

Charlie Kindel 5 P’s

Charlie Kindel – how to achieve focus in any endeavor you embark on by simply writing down the Purpose, Principles, Priorities, People, and Plan (the 5Ps). An endeavor could be a software development project, a job search, or a phase in your life. I have personally found the 5Ps a useful tool for small projects (e.g. prepping for a VC demo/presentation) as well as large scale projects that include 1,000s of people.

  • Purpose: Why do we exist? Why are we in business? Where do we want to be in the future? What will we deliver?
  • Principles: What are the non-negotiable rules and key strategies? How will we act?
  • Priorities: What’s the framework for tradeoffs? In what order do you do things? How much mass or energy do you apply to each element of the plan? What is not important?
  • Plan: How are we going to stage and tackle solving the problems? What are the known dates & forcing functions on the calendar?
  • People: Who’s accountable for every key part of the plan?

From https://ceklog.kindel.com/2011/06/14/the-5-ps-achieving-focus-in-any-endeavor/

Conway’s Law

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

Melvin Conway

Conway’s law was not intended as a joke or a Zen koan, but as a valid sociological observation. It is a consequence of the fact that two software modules A and B cannot interface correctly with each other unless the designer and implementer of A communicates with the designer and implementer of B. Thus the interface structure of a software system necessarily will show a congruence with the social structure of the organization that produced it.

Easily observed in organisations today Conway’s law still has merit and should be considered when designing software or reviewing organisational design.

From http://www.melconway.com/Home/Conways_Law.html

Also, from https://www.linkedin.com/posts/jonny-williams-83433836_do-you-care-about-conways-law-if-youre-activity-7009445165320790016-ZYTW/

So what might caring about Conway’s Law help you to do as a team enabler?

👉 Understand misalignment between the organisation’s communication structure and the systems and products they are creating.
👉 Recognise potential organisational impediments that might limit effective collaboration and communication.
👉 Offer practices, tools, and techniques that can help teams to navigate the limitations of the structure around them.
👉 Avoid common pitfalls and challenges that arise when working on complex systems.
👉 Help senior colleagues to understand that they play a role in shaping systems and products through their influence over communication structures.

Capture, organize, synthesize

Takeaway from a Mozilla user study studying how people find, save and share things on the web:

  1. Capture as much as possible. Capture without judgment: your thoughts are more valuable than paper. Externalize what you learn. Once an idea is captured in a tangible form you can begin surveying and manipulating it.
  2. Organize only after you capture. Filter, but don’t delete irrelevant information. Computers are big enough to search and store everything. Make them manage it.
  3. Synthesize into new meaning. Re-contextualize what you learn. This is the creative act. Experience becomes art, notes become a novel.

Most creative bottlenecks happen when you try to organize and synthesize before you capture. Spread it all out before you try to arrange it.

Many creative tools are designed for organizing first. Name the file before you can write in it. Create your Photoshop layer before you can draw on it. This causes friction.

From http://gordonbrander.com/pattern/capture-organize-synthesize/

Brainstorming

So how do you hold a brainstorming session that does not suck?

  • Invite the right people: Get a good group of people that are from a diversity of departments that have experience in different aspects of your product, company and customers and can bring those view points to the table. Make sure the group is not too big and not too small 6–10 is about right. Avoid inviting people just because.
  • Find the right space: Find an open space with plenty of space to write on — white boards or walls to add sticky notes to do the trick. Make sure the setup is conducive to moving around preferable with a big round table in the middle so people can face each other or the presenter.
  • Send an agenda: Make sure people know the objective for the session
  • Assign roles: Most of the attendees will be the brainstormers, however, your meeting will be that much more structured if there is an un-objective person whose sole role is to keep it moving, and make sure that everyone’s voice is heard — this is usually the facilitator. Assign ahead of time the note taker whose role is to keep track of the top ideas by writing them on the board and then sharing out the learnings and next step as a wrap up of the conversation. 
  • Introduce Brainstorming rules:IDEO’s 7 rules are clear and to the point and will help level set the group on what is brainstorming. Although design and product might be used to the sticky note exercises others might not be.
  • Get a facilitator: To ensure the session is truly unbiased and to learn yourself get a facilitator. This person, as an outsider, will not have baggage with the company and will allow you to be a part of the process.
  • Kick it off right: Get the data qualitative or quantitative to ground the conversation and why you are taking the time out of your day to have it. Prepare the high level anchor question for the group that will set the stage for your session “How might we….”, and then articulate any sub-themes that you know are already focus areas.
  • Start with a simple exercise: Get people out of their comfort zone and into a brainstorming mood with an easy opening exercise. For example ask the people in the room to spend 5 minutes drawing 5 others in the room. You’ll get a few “I don’t know how to draw” followed by laughter and people getting open to the idea that it’s not about the drawing ability but expressing the idea. 
  • Use tons of sticky notes and sharpies: Sticky notes are effective because they are fun and not like work so it allows every person to get out of their day to day and start thinking creatively. Why a marker and not a pen? Because this is about high level themes and ideas the more the better and what ifs rather than solving the how. If it does not fit on a sticky note using a sharpie it does not belong in this meeting as you have slipped into solution land. Don’t do this electronically if you can.
  • Remote team members: Try to get them in the room if possible. If you have a team member that is remote make sure they are paired with a scribe in the room. Make an effort to let them be heard and get them to see the boards and ideas getting generated.
  • Time constraint: Set a clear time for the sessions and keep the tempo moving (back to the need for a facilitator). Make sure there are stretch breaks and people stand up and walk around during the exercises as much as possible or you will start to loose people.
  • Take care of the people: Make sure there are nutritional snacks in the room. Brainstorming consumes enormous amounts of mental energy and sucks us into itself because like a game it’s fun. Make sure to take care of the people in the room and their brains will remain productive.
  • Focus the second half on getting to decisions: It is easy to get into a flurry of things you can do and ideas. That is the point of a brainstorming session. However, set aside the second half on clustering, grouping and getting to the focus set of things you will act on.
  • Accountability and next steps: Assign who is taking the next steps and sharing out what you uncovered in this brainstorm and the next actionable steps. Make sure that follow up is sent the next day so the energy you uncovered in this session continues and the ideas that made it get the right start. Share your findings with the rest of the company to get the others focused on learning and aligned with you.

Alternative brainstorming approach

  1. Set the ground rules and goals
    • Quantity over quality
    • No critiques
    • Build on ideas. Replace “yes, but…” with “yes, and…”
  2. Distribute sticky notes, sharpies
  3. Pose a question, user need or topic.
  4. Participants have 5 min to get as many ideas on sticky notes as possible. 1 idea per sticky note. Sharpies help because they are nice and thick — legible at a distance, and they prevent fine detail work.
  5. At the end of the 5m mark, go around and have people share their ideas.
  6. Put the ideas up on the board.
  7. Do this for 3 rounds. Toward the later rounds, new ideas tend to emerge, synthesized from others already shared.
  8. Cluster ideas by theme, topic, approach.

From https://medium.com/@elena.luneva/brainstorming-sessions-that-don-t-suck-23b12e7ccbd7 and http://gordonbrander.com/pattern/brainstorming/

Create Choices, Make Choices

The creative process…

Divergent thinking:

  • Yields options and choices
  • Suspend judgement and analysis
  • Focus on breadth not depth
  • Test competing ideas against each other

Covergent thinking:

  • Eliminate options – trim and edit
  • Make choices – polish
  • Practical way to decide among existing choices
  • Not good at probing the future

These 2 stages also map to problem-solving methodologies used by design and engineering.

Design uses a range of strategies from both stages. Intuition, and creative strategies like moodboards, form finding, and brainstorming are used to create choices. Iteration, design reviews, critique are used to make choices.

Production engineering is typically a process of making choices for implementation. It uses a strategy of modularizing problems — breaking problems into smaller parts, then solving each part. It can also be exploratory. Prototyping can be a process of creating choices when you take the build to think approach.

7 habits for developing a Technical Architect Mindset

  1. Decisions are not dichotomies of either/or.
    It’s not clicks or code, its clicks and code, or clicks at first, and then replacement with code. Or too much code, for the wrong reason, or too many clicks, for the right non-functional performance requirements. Some questions aren’t ‘Should I do this in clicks or code’ its ‘Should we do this at all’ or ‘What happens if I do it this way?’
  2. Becoming an Architect isn’t a destination.
    It’s a progressive journey that does not end. It may reach an inflection point (with a job title), but it’s not a mountain you climb where you reach the top and gaze down on the world below.
  3. You can’t study all the answers, but you can seek the experience.
    There is no book of ready-made answers to every situation. There are only things you see and hear and read. Ideas picked up from colleagues, war stories told by clients or friends, that project that failed, that idea that didn’t work out, that thing that succeeded. You do it over and over and over. The study gives you ingredients but cooking the meal, that comes from experience.
  4. There are no right answers. There are principles to learn and apply.
    There are better or worse answers, depending on the circumstances. Do you know all the circumstances? Have you considered the options for the answers? Do you know the questions to ask?
  5. It’s not about being ‘right’
    Indeed, you might not know if the design has succeeded or failed until years later. What was a success could be declared a failure with changing business conditions, changing assumptions, changing politics, changing technology. Often the right answer isn’t easily seen, it is simply your answer, supported by the reasons you can articulate and accepting the trade-offs you know come with it. If you think you are the smartest person in the room… then you are on your way to failure. Staggering insecurity is a feature, not a bug.
  6. The idea is the easy part, the persuasion is where all the work is.
    Can you convince a room full of people they are looking at the problem the wrong way? Can you justify your choices with the right props? Can you use diagrams, analogies, examples, stories, a raised voice or a timely question to win over a group of people?
  7. More here: https://www.youtube.com/watch?v=ND-dX-__I1Y&t=528s

From https://limitexception.com/another-7-habits-for-developing-a-technical-architect-mindset-448c9f3fec13