Engineering Handbook
Engineering is the core human resource at Spiffing and it is critical that engineering is performing at maximum capacity and is not hindered by the process. The goal of the process is to maximize engineering performance.
Processes are likely to change over time based on the feedback of the team and something that is included in the handbook today could be improved upon tomorrow.
Stay informed
Engineers need to keep themselves updated and similarly keep the other stakeholders updated through frequent, clear and organized communication, as described in the Employee’s Handbook. It is up to the person sharing the message to ensure that it is distributed across all the required channels. Keep the message sharing the document short and avoid discussions outside public (internal) channels.
Suitable channels for discussions, guidelines, or other long form text should be restricted to GitHub, JIRA or Markdown files (Obsidian.md) to keep a single source of truth.
As a technical documentation style guide, we vaguely follow Google’s developer documentation style guide.
Stay lean
The velocity that the engineering team delivers new features is fundamental to the company’s business model. High quality, frequent deliverables take priority over predictability. Delivering quickly gives us more opportunities and more feedback. Using an analogy: if you are practicing archery, given a 5-minute timeframe you are likely to score more points if you fire 20 arrows as opposed to using the entire 5 minutes to perfect a single shot.
Estimating
Teams will estimate tickets, however instead of using detailed story point estimates; estimates will be in relation to time. The variance between the time estimate and the actual time taken is the level of unpredictability. So if a task is expected to take 3 days, but in reality takes 4 days, then there is an unpredictability variance of 33%. While we aim to minimize this variance, we accept that we will never be 100% predictable and factor in the variance when planning releases. According to Parkinson’s law the work expands so as to fill the time available for its completion. We want to avoid this.
The Product Team is responsible for guiding the direction of our product. Technical leaders are responsible for guiding the technical architecture to meet those requirements. While Engineering Managers can and should participate in both of those conversations, their primary responsibility lies in project management: making sure their team is best positioned to meet both goals as effectively and efficiently as possible.
Speed matters
There is a lot of value in automating parts of your work that are mundane or repetitive. Any process that could be automated frees up cognitive load. For example, if every time you need to write a for-loop you need to check Stack Overflow, then you are paying the high price of context-switching each time. Creating templates, automating workflows, and ultimately coding faster allows you to learn more about your own code than you would if you do not automate the process. Speed matters - deliver quickly and invest in delivering even quicker.
Inspired by: https://scattered-thoughts.net/writing/speed-matters
Finish what you start
When you start a new task before finishing the previous one, average cycle times will increase. That happens because you’ll increase the number of items in progress but maintain the same throughput. Little’s Law illustrates this behavior by establishing a clear relationship between cycle time, work in progress, and throughput.
Teams that start tasks earlier than they should must also write specifications earlier. Therefore, they’ll waste an opportunity to gather feedback, digest it, and incorporate it into a feature’s specification, diminishing its chance of success.
Many times, teams will have multiple tasks in progress because moving a task from one stage to the next is costly. Consequently, these teams will attempt to transfer tasks from one stage to another in large batches to pay this high transaction cost only once. This should be avoided. The problem with large batch transferals in the software industry is that the cost of holding these tasks increases exponentially because their specifications perish, and change deltas increase, making it more difficult to find bugs. This increase in deltas also complicates change management, harming the system’s reliability.
One last benefit of working on smaller batches of tasks at a time is that it makes teams more predictable. Delivering the same number of tasks uniformly is better than delivering multiple tasks at once because it makes cycle times uniform too. In turn, those uniform cycle times help you make better forecasts, as there will be fewer possible outcomes when simulating (or estimating) the team’s performance.
Inspired by: https://lucasfcosta.com/2022/07/19/finish-what-you-start.html
The iterative approach
At Spiffing we develop using an iterative process where we do the smallest thing possible that gives our customer’s value and release it as quickly as possible.
Don’t invest a lot of time planning the details of a feature, as experience shows that these plans are likely to change. Only plan the first few steps and releases and then you’ll know better once it is released.
Don’t be embarrassed by the size of a feature on its first iteration and do not take it personally if a version you worked on is rewritten in the future. This is all part of the iterative approach. Most of the time, the simplest implementation turns out to be the best one. First implement it as quickly as possible. If it is a success, figure out how to scale it.
This is something difficult to get used to as very often, software developers are inclined to deliver more than requested and include small optional improvements. If we take smaller steps and ship smaller, simpler features, we get feedback sooner.
Working on a smaller feature also allows us to deliver a better quality feature. The effort required to deliver a great user experience on a small feature is considerably smaller than a great user experience throughout a large application.
If you need to decide something as a team, make a concrete proposal instead of calling a meeting to get everyone’s input. Having a proposal will avoid having everyone in the meeting brainstorming and makes better use of everyone’s time.
Retrospectives
Every month; each team is expected to conduct a retrospective. The scope of the retrospective is to provide a safe environment where everyone is able to voice their feedback and concerns. The results of this discussion could be a list of action points for the team that will be tackled in the next month. Avoid adding action points for the distant-future as often these get neglected.
The retrospective should include an agenda that covers topics from the past month. Among other topics, the retrospective should address:
- What should we double down on?
- What should we cut?
- What should we explore next?
During the meeting, a designated note-taker will update the note with the discussion and action points. A pull request is then created and all participants are requested to review. All retrospectives are available internally to all employees.
Retrospectives are a fundamental principle for the iterative approach as it allows us to improve our own processes too.
Dogfooding
Dogfooding is the practice of using your own products. At Spiffing, we try to dogfood everything. Dogfooding allows us to understand the value of our work and improve the product through our own feedback.
Small teams
At Spiffing we try to maintain small teams. A smaller team is easier to manage, communication is simpler, and ultimately more time is spent doing work, instead of managing it.
Each team should be autonomous & accountable for a part or area of the company’s product and the success of each team could be monitored through the use of a fitness-function; a metric uniquely assigned to measure a team’s performance. The fitness-function is decided between the team and management and should be straightforward to derive.
Code Standards
It is important to remember that quality is everyone’s responsibility. Everything you merge to main should be production ready. Familiarize yourself with the definition of done for your team.
How to code review
Code review is an important part of the engineering’s process, and while it may be simple to review someone’s work; it is more complex to review efficiently, avoid conflict and make decisions. As a code review standard, we follow Google Engineering’s guidelines