├── README.md ├── engineering.md ├── feedback.md ├── inclusion.md ├── pairing.md └── stories.md /README.md: -------------------------------------------------------------------------------- 1 | # introspection 2 | 3 | Questions and ideas to help us make sure we're doing the right thing. 4 | 5 | * [Inclusion](inclusion.md) 6 | * [Pairing](pairing.md) 7 | * [Feedback](feedback.md) 8 | * [Engineering](engineering.md) 9 | * [Stories](stories.md) 10 | -------------------------------------------------------------------------------- /engineering.md: -------------------------------------------------------------------------------- 1 | # Engineering 2 | 3 | If we could express all the subtlety of good engineering practice in a single Markdown document, then we wouldn't have jobs. So treat this as a small subset of concerns! 4 | 5 | ## Reusability and The Rule Of Three 6 | 7 | Make something reusable when it has been duplicated three times. 8 | 9 | Am I making something reusable before it needs to be re-used? 10 | 11 | If the current story takes longer because you're preparing for the future, you're risking engineering something that will never be used, and making this story seem more expensive when really the velocity hit should be in a later story. This misleads the PM and the client. 12 | 13 | ## Can I use a pattern? 14 | 15 | The use of patterns reduces diversity in the codebase, and diversity in the number of idioms that the readers of your code need to keep in mind. Complexity _requires_ diversity, so reducing diversity reduces complexity. 16 | 17 | ## Will it take longer to write this as a chore than to fix? 18 | 19 | If making code cleaner is quicker than writing what needs to be done in a chore, do it now. If it takes any longer to fix than to write up, stick it in Tracker as a chore for someone to pick up when they're waiting for a build, or when technical debt becomes problematic. -------------------------------------------------------------------------------- /feedback.md: -------------------------------------------------------------------------------- 1 | # Feedback 2 | 3 | Feedback means different things in different contexts, so it's worth thinking about what sort is meant: 4 | 5 | 1. **Appreciation** - _you've been working really hard and we love you_ 6 | 1. **Coaching** - _you can't expect to get everything right, maybe if you try..._ 7 | 1. **Evaluation** - _you don't know Golang well enough to anchor a team_ 8 | 9 | ## Giving Feedback 10 | 11 | When continuously learning we open ourselves up to being wrong and being criticised all the time. We make ourselves vulnerable to our colleagues, and so we each have a duty of care to be kind. 12 | 13 | Avoid the following: 14 | 15 | * **You always/never** - these absolutes are unlikely to be true, and only a Sith deals in absolutes 16 | * **You make me** - no, they don't: you are responsible for your own feelings and actions 17 | 18 | We often see our own shortcomings as a result of circumstance, and the shortcomings of others as character traits. Be aware of this bias. 19 | 20 | ## Difficult Conversations 21 | 22 | **Explicit disagreement is always better than implicit misunderstanding**. To move from the latter to the former requires some degree of courage, which is handily one of the five values of eXtreme Programming. If such conversations _don't_ require courage, then by definition they're not difficult. 23 | 24 | The following format is a handy tool for starting difficult conversations: 25 | 26 | > **I saw** you doing this, and **I believed** that, and **I felt this** 27 | 28 | Start with what you saw/heard/read. This immediately exposes any misunderstandings of fact. 29 | 30 | What was the conclusion you came to? Just because _you believed_ someone was being unreasonable doesn't mean that they were. Your interpretation of events is your own, and by focusing on your interpretation instead of making accusations you can help to avoid a confrontation. 31 | 32 | What was your emotional reaction? Reasonable people will not begrudge you your emotions. It's important to stop and think what really constitutes as an emotion though, because as adults we are atrociously bad at identifying them. 33 | 34 | |Feeling|Not A Feeling| 35 | |---|---| 36 | |Sad|I feel that the bug you committed has really hurt velocity| 37 | |Happy|I feel using Golang has made us much more productive| 38 | |Frustrated|I feel like you're not listening to me| 39 | 40 | You'll notice that in the above table the right-hand column are all beliefs, masquerading as feelings to make them irrefutable by others. 41 | 42 | ## Seeking Feedback 43 | 44 | Most folks feel uncomfortable giving critical (AKA useful) evaluation and coaching. A question that may elicit useful input is: 45 | 46 | > What do I do to get in the way of my own success? 47 | 48 | ## Receiving Feedback 49 | 50 | Negative emotional reactions to feedback fall into the following three categories. If you catch yourself having a negative reaction, see if you can identify if any of these apply. 51 | 52 | 1. **Truth** - _I don't agree with the facts you're putting forward_ 53 | 1. **Relationship** - _I don't think _you_ are allowed to say that to me, or I don't like how you're treating me_ 54 | 1. **Identity** - _That's not who I am_ 55 | 56 | Don't look for what's _wrong_ about feedback, instead look for what's _different_. That's where the interesting stuff lies, and that's where you'll get to the bottom of misunderstandings and different interpretations. 57 | 58 | Try to avoid changing the topic of conversation to "_well yeah, but you always end up committing commented-out code_". If there's another issue that comes up, that's fine to discuss, but deal with one situation at a time. 59 | 60 | ## Further Reading 61 | 62 | * [Thanks For The Feedback](https://www.amazon.co.uk/Thanks-Feedback-Science-Receiving-Well/dp/0670922633/) (Deejay has a physical copy) 63 | * [Difficult Conversations](https://www.amazon.co.uk/Difficult-Conversations-Discuss-What-Matters/dp/0670921343/) 64 | -------------------------------------------------------------------------------- /inclusion.md: -------------------------------------------------------------------------------- 1 | # inclusion 2 | 3 | ## Am I being kind? 4 | 5 | This underpins all of the other reflection points on this page. As our dear friends once used to say: _always be kind_. This shouldn't be conflated with always being _nice_: sometimes we have to disagree or highlight uncomfortable things in order to be kind. 6 | 7 | ## Am I using language sensitively? 8 | 9 | Am I choosing words with thought to how they are going to be interpreted? Could I choose to use other terms that are less likely to cause distress? Even if _I_ don't consider certain words offensive, am I taking other people's feelings into account? 10 | 11 | ## Am I considering people around me as individuals? 12 | 13 | Have I taken into consideration the needs and constraints of those around me as individuals? 14 | 15 | Some examples: 16 | 17 | * Have I made assumptions about this person based on how they appear or identify? 18 | * Do other people have experiences I have not had, that cause us to look at the world differently? Can I learn from this? 19 | * Has this person faced challenges that I'm not aware of, and might this explain differences of approach or belief? 20 | * Is it understandable for a non-native English speaker to mis-use terms? 21 | * Is this person uncomfortable because they've never met someone like me? 22 | 23 | ## Have I considered other people's biological reality? 24 | 25 | When pairing, we try and align people's body clocks as much as possible by starting at the same time, and taking breaks at the same time. Other people may have concerns and rhythms that might not be outwardly obvious. 26 | 27 | * What is my pair's sleep cycle like? Are they peaking in the morning, or afternoon? 28 | * Have I considered that another person may have gynaecological issues, such as cramps, PMT or menopausal hot flushes? 29 | * Do the people around me have different biological needs, such as reasons for more toilet breaks? 30 | * Is the person next to me fidgeting because they are diagnosed with ADHD or similar? 31 | * Are other people using medication that may require more frequent breaks, or may create behaviours that need accommodating? 32 | 33 | ## Have I helped create an inclusive environment by sharing my reality? 34 | 35 | Have I been brave and tactfully made other people aware of ways I'd like to be accommodated? 36 | 37 | Whilst we all have an obligation to be considerate and anticipate that others have needs which we do not, we can help our peers to help _us_ by communicating those needs. By discussing issues we can help normalise the things that make us different, and foster a culture where people can be frank and open. 38 | 39 | We hire for social sensitivity and kindness. We should be able to have conversations about how we can best work together. 40 | 41 | ## Am I recognising the strengths of other ways of doing things? 42 | 43 | Am I dismissing the tendencies of others to do things differently than I would as weaknesses? Am I considering that alternative approaches might balance out my own weaknesses? 44 | 45 | ## Am I respecting other people's ethics? 46 | 47 | Conflict and argument often arise out of differences in belief. If we believe in an objective truth (notwithstanding that such a belief is not universally held) we can often resolve those conflicts by first talking enough to understand what the difference of belief is, and then searching for an objective truth such that we can align our beliefs towards it. 48 | 49 | Some conflicting beliefs are more likely to be innate and practically unverifiable, at which point, tolerance is the only strategy available. Ethics fall into this category. 50 | 51 | An example: some people and cultures believe that the group is more important than the individual, and other people and cultures believe that the individual is more important than the group. A society that believed one or the other in totality at the population level would either be repressive or unable to function. Hence the subpopulations of each belief must co-exist at some level of dynamic equilibrium, and whether either is right or wong is a matter of philosophy and thus is unlikely to be resolved in a Slack conversation. 52 | 53 | _[The Righteous Mind](https://www.amazon.co.uk/Righteous-Mind-Divided-Politics-Religion/dp/0141039167/)_ is recommended reading. 54 | 55 | ## Am I communicating divisively? 56 | 57 | Exclusion is the opposite of inclusion, and division is both a cause and effect of exclusion. 58 | 59 | Am I discussing issues in a divisive way? Am I 'preaching to the choir' or am I communicating as if I'm talking to someone who holds different beliefs? Would I phrase things the same way if I was speaking in-person, one-to-one, with someone who disagrees with me? 60 | -------------------------------------------------------------------------------- /pairing.md: -------------------------------------------------------------------------------- 1 | # Pairing Introspection 2 | 3 | ## What does my pair think? How does my pair feel? 4 | 5 | Above any suggestions here, ask your pair what they think, or how they feel about any given situation. 6 | 7 | ## Am I denying people the opportunity to learn? 8 | 9 | Maybe you're in your comfort zone and being super-productive. If things slow down when you stop driving, maybe that's a sign that your pair could do with more practice. 10 | 11 | ## Am I allowing my pair to go at their own pace? 12 | 13 | **It is vital that people are allowed to work at their own pace** without explicit or implicit pressure. We pair so that people can learn and gain context on systems; if one half of the pair can't keep up, then they're not learning anything and not gaining context. Any slowdown is a cost that EngineerBetter is willing to absorb. 14 | 15 | If there's a speed discrepancy between you, consider setting a timer and taking turns. 16 | 17 | ## Am I explaining what I'm doing _before_ I do it? 18 | 19 | Sometimes its easier to type than to explain an idea. It's more socially awkward to remove something that's already been written than it is to critique an idea that is merely being discussed. Writing first and explaining after may put your pair on the back foot. 20 | 21 | ## Am I letting my pair think and make mistakes? 22 | 23 | This point is most pertinent when pairing with someone of lesser experience. 24 | 25 | People are less likely to remember a fact if they are told it than if they discover it for themselves. Whilst it might be quicker in the short term to tell people answers, in the long term it may be better to let them think, try something, and find out for themselves why it is wrong. 26 | 27 | ## Am I giving goals, or instructions? 28 | 29 | When pairing with someone with less experience, it can be tempting to give them very direct instructions "_type 'git pull origin master'; hit return..._" Giving goals instead allows your pair to problem solve for themself, eg "_Next we need to get the latest code onto this machine._". 30 | 31 | ## Am I coasting too much? 32 | 33 | When was the last time I drove? It's not so much about 'doing your fair share' as making sure that you strengthen the right neural pathways to ensure that you really understand what's going on. Could I take over if my pair had to disappear somewhere? 34 | 35 | ## Have I checked that my pair really understands what I'm doing? 36 | 37 | Is your pair responding with "yeah", "uh-huh", and not a lot else? Maybe they understand enough to tenuously follow what you're doing, but not enough if you asked them to drive. 38 | 39 | ## Can I explain a different way? 40 | 41 | If your pair doesn't get what you're doing, perhaps you can try explaining the issue in a different way. Although the idea of learning styles is largely discredited, the notion of 'multiple intelligences' continues to be useful as a framing tool. If you've tried explaining with words, perhaps a diagram would help? If describing the details of an API isn't helping, maybe try talking through the flow of calls? 42 | 43 | ## Have I spoken up if I don't understand something? 44 | 45 | It takes courage to slow someone down and to tell them that you don't understand. Keeping quiet won't make anything better, and the only solution to not understanding something is to take the time to understand it! 46 | 47 | ## What prompts me to start driving? 48 | 49 | Do you always take control after a certain point? Is there a pattern to the parts you take the keyboard for? 50 | 51 | ## If I'm pairing with someone who knows less than me, how can I help them learn? 52 | 53 | There can be many pitfalls when developers with different skill levels try pairing. 54 | The natural instinct for the senior developer is to explain everything without allowing time for the junior developer to discover answers for themselves. Try using open ended questions instead of jumping straight into explanations. 55 | -------------------------------------------------------------------------------- /stories.md: -------------------------------------------------------------------------------- 1 | # Stories 2 | 3 | Writing good stories is hard. 4 | 5 | Above all else, remember the promise upon which trust between the customer and the engineering team is based: 6 | 7 | _We will sustainably deliver the most important thing via the shortest route._ 8 | 9 | We must demonstrate to stakeholders exactly what customer value we have delivered and are working on at any given time. We can't work in a deadline-free, no-fixed-deliverable methodology unless we keep the above promise, and more importantly, _are trusted_ to keep the above promise. 10 | 11 | ## Who is the customer? 12 | 13 | The persona should not be the engineering team, nor the PM. The persona should be an end user or customer. 14 | 15 | Creating a persona of the engineering team leads to mistaking chores for stories, and makes the team appear to be delivering value when in fact they are making themselves more efficient. The pay-off for this should be increased velocity later, not the earning of velocity now. 16 | 17 | ## Does this story say what a persona can now do? 18 | 19 | What is it that the customer can do after the story, that they couldn't do before? 20 | 21 | ## Does this story deliver customer value? 22 | 23 | If any story does not, to the best estimate of the PM, deliver customer value, then we're abusing the trust of business stakeholders. Any time we dress up a chore as a story, we're lying to the product owner. 24 | 25 | ## Does this story express a value statement? 26 | 27 | Stories must express customer value in a testable statement. Stories must not be imperative instructions of "_do the thing_", as these instructions are meaningless to non-technical staff and could be chores in disguise. 28 | 29 | * Good: I can cross the river. 30 | * Bad: Build a bridge. 31 | 32 | Perhaps the engineering team is better at building rafts than bridges. Why do we want a bridge? 33 | 34 | 'Do the thing' stories can also be hard to test. The acceptance criteria often end up being 'the thing is done'. 35 | 36 | ## Can the story be expressed more succinctly? 37 | 38 | Can you use fewer words to express the value to be delivered? 39 | 40 | * Good: Visitors can see the home page 41 | * Bad: As a visitor I want to be able to see the home page 42 | * Bad: As a visitor I should be able to see the home page 43 | 44 | If there's only one persona in your backlog, you can omit the "As a someone" too. 45 | 46 | ## Does this story have too many deliverables? 47 | 48 | In most cases, it's better to have many small specific stories than one that asks you to do three things. 49 | 50 | Tell-tale smell: the story has a list of things for you to act upon. 51 | 52 | ## Is this story specific? 53 | 54 | * Bad: As an app developer I can find all the docs in one place 55 | * Good: As an app developer I can find the logging docs on GitHub 56 | * Good: As an app developer I can find the networking docs in Confluence 57 | 58 | If a story doesn't say _exactly_ what needs doing, then we can't estimate complexity, and there could be all sorts of assumption hiding, ready to bite us in the backside. 59 | 60 | Tell-tale smell: the story mentions an unspecified plural 61 | 62 | ## Avoid "As a Persona I want..." 63 | 64 | If you didn't want it, it wouldn't be in the backlog. 65 | 66 | ## How should I express my acceptance criteria? 67 | 68 | Two common formats which work, depending on context: 69 | 70 | - Gherkin language (GIVEN, WHEN, THEN) 71 | 72 | This is good when you need to be explicit about the start and end state. Often this format depends on shared understanding of what the various clauses mean. 73 | 74 | - Explicit list of steps 75 | 76 | This is easy for engineers to follow, but requires a more granular level of understanding on the part of the PM. 77 | 78 | ## Do the acceptance criteria define the customer experience? 79 | 80 | It is the Product Manager's responsibility to define the interface of the product. Acceptance criteria should define what the customer experience and interface are. 81 | 82 | Imagine a backlog for a CLI tool. A new feature is to be added to allow a size of VM to be specified. 83 | 84 | * Good: When I run `cli --vm large` I get a large VM 85 | * Bad: When I ask for a large VM, I get one 86 | 87 | The PM is the guardian of the customer experience, and such an important facet should not be left to the whims of whichever engineer happens to pick up the story. 88 | 89 | ## Is this a chore or part of a story? 90 | 91 | The outcome of a chore should be to increase the long-term velocity of the engineering team. 92 | 93 | A chore should _not_ be a technical task that is on the critical path to business value. If something that _must_ happen to deliver a story is broken out into a chore, this disguises complexity - it makes a story look simpler and shorter. Working on chores that are actually parts of stories can make it look to stakeholders as if the engineering team is spending time working on its own stuff instead of on the business' priorities. This is dangerous in a low-trust environment. 94 | 95 | There will be times when it makes sense to play a genuine chore before a story, in order to make delivering that story easier. This is different to taking a critical part of a story and separating it out into a fake chore. 96 | 97 | Possible reasons to break this rule are to make progress more visible. However, this then obscures information that the original story was either too big or unavoidably complex. 98 | 99 | ## Is this a spike or part of a story? 100 | 101 | The outcome of a spike is information - usually _"can this be done?"_ 102 | 103 | A spike should not be used to work out _how_ something should be implemented. Deciding on the best/most appropriate implementation is part of every day work on stories, and every engineer has the authority to make whatever decisions they think are best. 104 | 105 | If a decision is poor, there are plenty of after-the-fact safeguards: 106 | 107 | * A new pair rotating onto the story 108 | * Other engineers later encountering the code, and raising concerns in a retro 109 | * Lower velocity as a result of the sub-optimal choice 110 | 111 | If the tests pass, and the acceptance criteria are met, then we can live with any technical decision until it causes a problem. If it never causes a problem, then we don't have to fix it, and it probably wasn't a poor choice to start off with. 112 | --------------------------------------------------------------------------------