#fundamentals
89 posts

Don’t be a jerk: write documentation

Documentation can be minimal and yet helpful. Take whatever you have in volatile formats (email, chat logs, shell I/O) and paste it into more durable ones (README files, diagrams, websites, FAQs, wikis).
Read more

Don’t be a jerk: write documentation

  • Documentation can be minimal and yet helpful. Take whatever you have in volatile formats (email, chat logs, shell I/O) and paste it into more durable ones (README files, diagrams, websites, FAQs, wikis).
  • Document based on your audience:
  1. For newcomers, focus on what it does, why you wrote it, who should be using it and for what, how it should be used (how to build, configure, run and get started), and where additional information may be found; do not display the source.
  2. Regular users could do with a reference manual, examples, EDoc/JavaDoc/Doc, wiki or website, and API descriptions.
  3. Contributors should have access to the source repository, as well as project structure and architecture (where to find out about specific functionalities and where new features should go), the project principles, tests, issues, and a roadmap.
  • An easy way to get started is to imagine you are talking to a new user. Then vary the user and add different scenarios (of their business context and experience/knowledge, budgets) to expand the documentation until it is comprehensive. Finally, you might split it up into categories for different people or reimagine/format it for different media/platforms.
  • Another approach is to find a problem a user might face and show them how to solve it.

Full post here, 11 mins read

Four magic numbers for measuring software delivery

Lead time, deployment frequency, change failure percentage, mean time to recovery/resolution..
Read more

Four magic numbers for measuring software delivery

  • Lead time to validate, design, implement and ship a new valuable thing. Consider two types of lead time: (a) feature lead time: the time to move an item from high-level requirements to feature release and (b) deployment lead time: the time from merging to master to the component being in production.
  • Deployment frequency, understood as number of times per developer per day you ship to production. Your deployment frequency may ebb and flow, from 5-10 on a busy day to none the rest of the week. Establish a baseline over 4 weeks: say, 1 production deployment per day on average.
  • Change failure percentage, ie, the proportion of red deployments, bugs, alerts, etc. Defining change failure rate as bugs per production deployment over a given period, aim for about 10% or less with medium or high-priority of customer impact.
  • Mean time to recovery/resolution. For mean time to resolution, aim for less than a working week.
  • Considering feature lead time as a key performance indicator can help you break features up and deliver faster. This might also decrease lead time per deployment.
  • Convert generic support tickets into bugs with customer impact implications so they can be tracked better. Make bugs more visible can also make bottlenecks in the resolution process more apparent.
  • Count red production deployments and production alerts as a change failure.

Full post here, 9 mins read

Inefficient efficiency

Latency (measured in time units) is the time between a stimulus and a response, while throughput (measured in deliveries per time unit) is the rate at which the system meets its goals.
Read more

Inefficient efficiency

  • Latency (measured in time units) is the time between a stimulus and a response, while throughput (measured in deliveries per time unit) is the rate at which the system meets its goals.
  • Sometimes latency and throughput interfere with each other. Do you field a request and respond before taking the next request (low latency for the first customer but overall lower throughput), or do you accept the second request while processing the first for higher throughput?
  • You make latency/throughput tradeoffs every day and most of us are biased towards throughput. For example - you carefully plan all foreseeable architectural improvements instead of initiating the first profitable change you come across.
  • Instead, you should optimize for latency. For example - if preferences are likely to change between requests (high rate of change), so you can adapt, which is less wasteful.
  • To decide between throughput and latency, consider the cost of delay, whether you might learn something that changes your approach subsequently, and whether external factors might force a new approach.

Full post here, 4 mins read

Feedback is not a dirty word

Without a good feedback system, pockets of disagreement can grow into resentment, distrust and eventually organizational failure. Feedback is also the only way to achieve true personal growth.
Read more

Feedback is not a dirty word

  • Without a good feedback system, pockets of disagreement can grow into resentment, distrust and eventually organizational failure. Feedback is also the only way to achieve true personal growth.
  • For critical feedback to be effective, give it in private and with positive intentions, be specific and factual, and use a non-violent communication format: ‘when you do , I feel because the story in my head is ’.
  • Set up review sessions regularly (ideally weekly) at an expected time.
  • Be receptive to feedback and sidestep your ego’s fight or flight response by evaluating ideas objectively and viewing feedback as a gift.
  • Once you have heard the feedback, repeat what you heard, request confirmation and keep asking ‘Is that all?’ until you are sure the other person is done. Finally, think objectively about the feedback and suggest an action to resolve it.
  • Ensure that feedback is a part of your culture and an expectation from managers. Hold weekly one-on-one meetings, with structured time in the end for mutual feedback and put it all on record.
  • Publicly seek feedback from your team and discuss it. As a leader, publish written feedback from other leaders for the entire company and discuss ways you are trying to improve.

Full post here, 5 mins read

How to be a good software engineer mentor

As a mid-level or senior developer helping a junior developer grow, show them things they can only get from experience, not just coding.
Read more

How to be a good software engineer mentor

  • As a mid-level or senior developer helping a junior developer grow, show them things they can only get from experience, not just coding.
  • Explain business-side decision making. Have your junior sit in on meetings with clients or production managers (or explain later), so they have context and understand where their tasks come from.
  • Do a demo and discuss the business logic of the project they are working on, so they can see the user perspective and know why certain decisions were made.
  • Cover best practices in code reviews: discuss better solutions if they have poorly written code even if it works. Decode jargon, especially for core concepts, and explain the team’s code decisions so they can see how applications grow.
  • Hear them out before you tell them the ‘right’ way. Resist rushing them towards the end of a sprint and let them learn to think fast and critically and to commit to decisions. Listen and then explain why (if) you need to make a different choice.
  • Talk them through your thought process while coding, then reverse roles: hearing them think lets you notice when they aren’t using a concept correctly and makes them more aware of their own process.

Full post here, 5 mins read