How I wrote my first non-fiction software leadership book

Posted on Sep 23, 2020

September 23 2020

Around 10 months ago I began work on a new side project to author a book on software engineering leadership. I was confident I went in eyes wide open, knowing it wouldn't be an easy undertaking, but in the end it was considerably harder than I had even imagined. As a retrospective I wrote this post to share the 18 (yes way too many) stages I took when writing my first book "Leading Software Teams with Context, Not Control". In hindsight, I could have easily reduced the amount of stages I went through, however, you always learn considerably the first time you do anything. I'm sure there are many more effective ways to author a book, but as a first time author this is the approach I took (which did evolve as I worked through the project). So yes, you probably shouldn't use this as a definitive guide if starting out on writing your own first book!

Here is a visualisation of % of book completed against hours invested:

Where it all began...

It all started with a relatively innocent Google Doc working a few hours every few days, and ended with a GitHub repo with each chapter in Markdown, a bunch of CSS and an automated pipeline to generate epub, mobi and PDF file outputs for each of the platform I was to publish the book to. Oh, and dedicating 3 hours every night to get this project over the line.

Part 1 - Defining the chapters

Completed: 1%

Time taken: 12 hours

I spent the first 12 hours defining the structure of the book. This involved breaking it down into 20 chapters focused around aspects I believed were important in relation to software engineering leadership. Within each chapter I listed a small amount of dot points on topics I planned to focus on.

Lesson learned: Start with a GitHub repository and use Markdown from the very beginning! Also set yourself up on https://leanpub.com/ - it's an amazing self publishing platform that encourages you to publish early and publish often.

Part 2 - Defining the chapter structure

Completed: 2%

Time taken: 6-7 hours

After analysing a selection of well written books I had previously read, it was important for me to ensure a consistent structure and flow throughout each chapter for the user. I defined a 5 part structure for each chapter to follow. You can think of these as top level headings within the chapter. However, you will notice in my book these headings don't exist, yet each chapter follows that structure :

• What: An overview of the topic the chapter was about
• Why: An explain why this topic is important in relation to software engineering leadership
• Story (optional): An example or story I could share from my own experiences
• How: Approaches on how to implement this topic within your own software engineering team
• TL;DR: 3 important takeaways from the chapter

Lesson learned: After initially spending a few hours on this, I ended up reviewing 6 of the best books I had read and defined a structure that took the best of each.

Part 3 - Brainstorming each chapter

Completed: 5%

Time taken: 40 hours

At this point in time I began drafting out each chapter as a set of more refined bullet points that aligned to each of the structure headings listed above. Spending around 2 hours on each chapter allowed me to get as many details as I could out of my brain and into the Google doc as quickly as possible.

Lesson learned: Choose your language up front and stick to it. I started with English (AUS), then moved to English (US), then later converted it to English (British). Wasn't the best use of time...

Part 4 - Drafting out each chapter

Completed: 15%

Time taken: 80 hours

With each chapter now a set of refined bullet points ranging from 1-4 pages, this part involved bringing each chapter together to represent a roughly formed draft. Each chapter was partially readable and had a level of flow to it. This took around 3-5 hours per chapter. At this point in time I had 18 chapters that were coming together nicely, but had also outlined 12 additional possible chapters as notes down the bottom of the document - which was clearly too many. I had also begun reordering chapters to improve the narrative of the book.

Intermission

At around this point in time my wife and I discovered we had a baby due in 7 months. It was at this point I began to realise I needed to finish this project before then - I now had a deadline. But... as it was still a fair way out, I didn't take the deadline as seriously as I should have. However, in a few months time I would.

Lesson learned: Set yourself a deadline for the project, as well as a deadline for each smaller milestone. Then commit 'X' number of hours per week to dedicate to authoring your book.

Part 5 - Adding in data points and examples

Completed: 24%

Time taken: 80 hours

It was now the time to bring hard facts, data points and career examples into each chapter to back up the claims I was making. For some chapters this was around reinforcing claims I was making from experiences I had had throughout my career. For others it was crawling through my twitter history that I use to share articles I have found value out of over the years, to find the specific content that helped support my books content. This took around 4 hours per chapter.

Lesson learned: Correctly collate and document your books references at this point, not at the the end of the project.

Part 6 - Research break

Completed: 25%

Time taken: 2 hours

At this point as I had the perception I was progressing well. I began to research more tips and tricks around publishing a non-fiction book. One valuable insight I gathered was when writing a book you should start of by draft 4-5 'fake reviews' that you would theoretically like people write about your book once they have read it. This is done in an effort to continually refer back to so you can keep yourself honest in regards to the content you are authoring into your book. You want to write positive and negative reviews. I came up with:

• This book is a great toolkit of practices I can essentially copy and paste into my role as a software team leader.
• I found valuable insights into how to setup specific initiatives I should be orchestrating in my role as a software engineering leader of multiple teams.
• I enjoyed the top 3 summary items at the end of each chapter which helped reinforce key items I need to remember.
• The exercises included within each chapter have been really easy to adopt into my leadership role.
• Although I learned different approaches to managing software teams, this book focused more on leading multiple teams, than a single software engineering team.

A quick break

At this point I was feeling rather positive. I had written most of the book, and had convincing data to back up my content. All that was left was to do a few rounds of clean up and generate an ebook for publishing. Easy right? At this point I thought I was about 65% through the project, in reality I was about 20% through.

Part 7 - Clean up stage 1

Completed: 40%

Time taken: 125 hours

Starting from chapter 1, I began working through each chapter to fix up grammar, improve the flow of sentences, include additional detail where needed and deleted content that was just unnecessary. The first 6 chapters within the book were sequential, whereas the subsequent chapters were all independent and could be read in the readers preferred order. I invested a lot of time attempting to make chapters 1-6 to flow seamlessly so as to not confuse the reader. I spent over 16 hours cleaning up just the first 6 chapters, rewriting, and rewriting more. This is when I hit my first wall, when I began to realise I was definitely not 65% through and more like 20% through authoring this book. I now realised I needed a more structured time investment to progress. I began to dedicate 3 hours, 3 nights a week on this project. Chapters 7 onwards were slightly easier to clean up - but still a considerable amount of work.

Lesson learned: Set up a schedule for time investment earlier on that you can commit to.

Part 8 - Clean up stage 2

Completed: 55%

Time taken: 98 hours

The book was now at around 55,000 words and my Google doc was beginning to struggle from a performance perspective. But I persisted with it (for the moment). Starting again from chapter 1, I began a second pass on improving grammar, removing duplication and general tidy up. I eventually had to condense my first 6 chapters into 5 chapters as it just wasn't working the way I had originally authored it. This took up a lot of time and was mentally challenging. I also ended up deleting an entire chapter (chapter 18 to be specific) as the book was becoming too lengthy and that chapter added the least value. Again, mentally very hard to delete large blocks of content that I had already sunk many hours into. However,  in the end it was the correct decision. At this point I also made the hard decision to remove all other 'potential chapters' that I still had as notes down the bottom of the book. Maybe this will appear in my second book sometime in the future. I spent around 2 hours on each chapter, and again more time refining chapters 1-6.

Lesson learned: It is entirely ok to delete large amounts of content within your book if it will lead to be a better experience for your readers - but yes it will be mentally challenging to do so.

Part 9 - Defining and setting up 'the matrix'

Completed: 57%

Time taken: 12 hours

I was now spending 3 hours each night, 6 days a week authoring this book. I had around 8 weeks to go until the baby deadline would arrive, and I was running very short on time. The few people I was talking about my book with to I would confidently let them know I was tracking well, however, personally I was not so sure. Throughout the previous month, I was furthering my investigation into what makes a great non-fiction book. Again, something in hindsight I should have undertaken at the start of the project. I came to the conclusion that I needed to define 8 measures each chapter should satisfy for the reader. They were:

• Clearly state the problem the chapter was written to provide a solution for
• Provide an actual solution the reader could adopt within their own team/role
• Include two data point facts in each chapter
• Include 1 example or personal story
• Relate to the readers experience to connect with them throughout the book
• Share something important the reader probably wasn't aware of
• Include a call to action and/or summary at the end of each chapter
• Make claims that are as strong as they can be made without becoming false

I put together a simple matrix (eg: table), with those 8 measures above as columns and each chapter as rows so I could track which measures I had accomplished.

Lessons learned: Spend a week or so researching what makes a great non-fiction book before you begin. As well as this create your own matrix to help keep you honest to your readers in each chapter.

Part 10 - The matrix phase 1

Completed: 65%

Time taken: 69 hours

With the matrix defined, I worked through each chapter ensuring it tackled each measure, and where it might not be relevant marked it as N/A. In this phase, I skipped over any item that had a potential to require considerable time investment. I spent around 2-4 hours on each chapter.

Part 11 - The matrix phase 2

Completed: 70%

Time taken: 46 hours

This part involved going back through each chapter and filling in the missing gaps within the matrix. Although some chapters took longer than others, I averaged 2 hours per chapter. At this point in the project, I began to feel as though I had a book that tackled the key problems I was aiming to.

Part 12 - Crafting the title

Completed: 75%

Time taken: 12 hours

I knew I needed to proof read the book again (at least once or twice more), however, I needed a break. I had hit a writing exhaustion wall. It was now time to come up with a title.. Easy right? Ok probably easier than finding a name for a new startup with an available domain name. But still hard! 

I wanted something I could relate to, that would catch the interest of a potential reader. After around 12 hours of brainstorming many different titles and variations, as well as gathering feedback from a few individuals within my network, I settled on "Leading software teams with context, not control". Context over control was a chapter in my book, and it is a leadership methodology I have followed for many years - so it seemed quite applicable.

Lesson learned: Procrastinate on a title until you have one that resonates well with you.

Part 13 - Authoring surrounding chapters

Completed: 82%

Time taken: 17 hours

With a title in place, I now needed to author the surrounding chapters within the book which included:

• About the author
• Why the book was written
• Acknowledgments
• Glossary
• Notes

Lesson learned: References are still as hard and time consuming to create as they were in the university assignment days.

Part 14 - The final proof read

Completed: 90%

Time taken: 56 hours

With the book mostly complete (90%), it was time for the final proof read. I spent just over 2 hours reading through each chapter very slowly, in large font to ensure it flowed well for the reader. I also began using grammarly.com, a great tool to improve grammar and sentence structure.

Lesson learned: Start using the grammarly.com app from the very beginning.

Part 15 - Creating a cover page

Completed: 91%

Time taken: 28 hours

What can I say, I spent too much time finding the 'right' shade of blue. I used a great online tool called figma.com to design the cover page. I ended up creating 4 cover pages for the different stores I published the book to.

Lesson learned: Probably a good idea to outsource this to a freelancer.

Part 16 - Building the epub files

Completed: 94%

Time taken: 46 hours

I had now written the ebook, how hard could it be to create a beautifully formatted ebook? Well first of all if you want any control over your styling you best be using markdown files with CSS. That was 16 hours lost converting my entire google doc to markdown. Then you need a tool to convert markdown to epub. I ended up using pandoc.org - a very handy tool. If you are planning on using pandoc, be sure to read the documentation carefully and add in all the correct CLI arguments to create page numbers, TOC, title page etc... It can't do everything, but it can do enough.

After spending a many days experimenting with different approaches, I ended up scripting what I was doing into a repeatable process to generate epub files on the go. I then spent a few days crafting CSS to carefully format the epub into a well presented and readable format.

This was definitely more time consuming that I had expected, but it was a nice change to jump back into the code.

Lesson learned: Start with markdown, accept that large tables are near impossible to format well in ebooks, and finally script your build process for the different ebook formats and sample formats. I regenerated my ebook over 200 times while testing out formatting.

Part 17 - Professional copy editing

Completed: 97%

Time taken: 38 hours

Cost: Approximately $1,600

Every book requires professional copy editing to perfect it for your readers. There are so many options out there, in the end used the reedsy.com marketplace to find a great copy editor.

Lesson learned: Pre-book in a copy editor, as it took around 4 weeks for me to fit into their schedule once agreeing on terms.

Part 18 - Submitting the ebook

Completed: 98%

Time taken: 7 hours

It was now time to publish my ebook to the relevant online stores. I started with LeanPub.com, then Amazon.com, Apple books & finally Google play. It took some time setting up relevant accounts, tax information, author bios etc...

Lesson learned: Upload your epub to Amazon.com, then download the generated mobi file and use that for platforms like LeanPub. Also mobi will require some minor CSS additions for formatting.

Part 19 - Preparing for print on KDP

Completed: 100%

Time taken: 19 hours

After spending nearly a year authoring my book into an ebook format, why not publish a paperback as well. Amazon KDP (Kindle Direct Publishing) is a great self publishing platform for on-demand printing of paperback books. You need to upload a print ready PDF, with a cover. To do this I converted the epub file into a PDF using 'ebook-convert' which is part of the calibre application. I also needed to inject in additional CSS for print specific styles. Preparing for print is a rather simple process using KFP, the only downside is a 72 hours approval window after each new upload. However, KDP scans your PDF for formatting issues and alerts you to fix before publishing. Once published you can order cheap author copies for your review.

Lesson learned: You can apply specific CSS to your print version, for example page breaks, table styling etc... You will want to do this once you have finished your book though to avoid any unintended formatting issues if you adjust large amounts of copy.

Project complete!

That's it, 10 months, 792 hours later, I had a 23 chapter book with 349 pages, 68,000 words available in eBook and print formats available globally. It was quite a journey, where at multiple points I thought about pulling the pin, but eventually pushed through and completed the book (unlike many other side projects I still have 'in-progress'). All that is left is to promote the book :-)

What were my final take aways?

• Authoring a book is harder and more time consuming than you will ever realise. Go in prepared for this realisation.
• Carve out consistent time out each week, break your project into smaller milestones and set deadlines for each.
• Research aspects of successful books, and draft a plan before starting. Still evolve it as you go though.
• You will learn to correctly spell some of those words that you used to always use spell checker for.
• Automate you ebook and print generation. I probably regenerated my ebook over 200 times, automating the process will be worth your time investent.

If you are interested in a copy of my book "Leading Software Teams with Context, Not Control" you can purchase on here.

Read More

Balancing technical uplift with product development

July 30 2020

Closely behind the holy wars of programming languages, is the battle of technical uplift versus product feature development. It exists in every software organisation around the world, however, some are able to better balance the two more evenly. Software developers are best placed to understand how to keep their platforms stable, online and scaling with customer growth demands. This results in the software team typically being motivated in focusing on technical uplift initiatives to improve scalability and reducing technical debt. Whereas the product team knows and understands the customer, and are motivated to continuously find new ways to engage and inspire them. This results in the product team focusing on initiatives that drive new capabilities and features that deliver a better customer experience than their competitors. Finding a technique to balance both of these potentially conflicting and competing priorities can be challenging and fuelled with justified passion from both sides. In mature and collaborative organisations though, it promotes healthy and constructive debates on what initiatives add greater value.

It is important to note that when referring to technical uplift, it is not specifically referring to only technical debt. Although technical uplift sometimes needs to occur due to long standing technical debt, technical debt is the result of specific historical decisions knowingly being made that results in a platform becoming more expensive to maintain or potentially scale. Some technical debt is bad debt, in that the cost of repaying those decisions becomes exponentially higher as time passes. Whereas other debt is more easily repaid at a later point in time. A crucial call out to understand is that new technical debt is accepted and taken on as a team, it isn’t forced onto the team by stakeholders - that is not a software engineering team culture you want to let evolve.

Why the decision is not binary

Balancing technical uplift and product feature build rarely needs to be a binary decision. From a software developer’s perspective, they work day in and day out within the platform’s codebase. They understand many of the pain points that result in scalability issues, areas of the code that every software developer avoids working on because the slightest change can cause unknown production issues, or the frustration of repetitive and manual processes that have evolved over time making the team ineffective. By failing to ensure the software team has a voice in prioritising technical uplift can result in three key impacts. Firstly, the organisation is not trusting the most experienced people working on the platform who understand the key technical issues being faced and how to improve them. Secondly, the organisation is not solving fundamental problems within the platform that will enable faster and more effective development and deployment of new product features into production. Lastly, without trusting the team and empowering them to improve the codebase and platform, it will be detrimental to the culture within the team and ultimately the higher performing software developers will disengage and move on.

From the product perspective, product owners and product managers attempt to deliver the best possible customer experience. They listen to customers, gather feedback and aspire to release a range of new features to continually attract new customers or retain existing ones. They understand that doing this well will lead to an increase in profitability for the organisation. By not prioritising the development of new capabilities, a platform will be irrelevant as it eventually loses customers to competing organisations and platforms. The thought of losing customers is demotivating for anyone working within a product role and can lead to an increased turnover of product owners and managers within the organisation.

As mentioned above this is not a binary decision, in that an organisation does not have to focus 100% on technical uplift or 100% on product feature build. A healthy balance needs to be found between the two to ensure platform scalability, new product development and retention of team members within the organisation. Even an early stage startup focused entirely on growth needs to dedicate a percentage of time on technical uplift to ensure platforms don’t become too expensive to scale and maintain which is known to have crippled many startups throughout their scale-up phase. Twitter shared an insightful post on their blog many years ago that spoke to serious performance issues in relation to their search capability. It was a result of years of technical debt in their Ruby codebase which made it challenging to add features and improve the reliability of their search engine. However, the organisation trusted and empowered the software engineering team to implement a solution which resulted in the rewrite of their search capability which improved searching speeds on twitter three fold.

Don’t be binary

In a previous software leadership role, I remember walking into a team facing considerable technical challenges specific to the scalability of the platforms running in production. This was due to the organisation scaling up incredibly quickly over their recent years which had resulted in unfortunate architectural decisions being made, as well as a continual focus on product growth with little to no priority on technical uplift. The software team was frustrated and they were beginning to see a higher than normal number of resignations. This needed to be resolved. Over the next 24 months the team began focusing their efforts on fundamental technical uplift. Platforms were decommissioned, others were re-architected, all alongside a much needed modernisation of software engineering tools and practices. The team was investing effort into rapidly evolving their platforms to support the organisation’s expansion aspirations. The first 18 months brought a breath of fresh air within the software team as there was now motivation and support to improve. At this point in time, the software teams were focusing on average 80% of their efforts on technical uplift which was the nearly exact opposite 18 months prior. Throughout the next six months though, the team that had once only wanted to improve their technology and platforms began to question their purpose within the organisation. Sure, their platforms were considerably more stable and scalable, they were even able to deploy production changes within hours instead of months, but something was missing. The organisation's product vision was missing and teams started asking questions:

• Why are we building this product?
• Who are our actual customers?
• What is our vision for this product?

The mindset across the group began showing signs of drifting back to where it was 18 months prior, which leads me to the point. It is unhealthy to have a software team focus 100% of their effort on technical uplift and ignore product feature development. Likewise you cannot expect a software developer to remain engaged if focusing solely on product feature development and disregarding any technical uplift or hygiene. A balance is required, and this balance is different in every team. This balance may also evolve every 6-12 months due to an organisation's ever changing environment. As a software leader, you need to be constantly pulse checking where teams are spending their effort. Your role is to motivate teams with a balance of technical uplift and product feature development and ensure a purpose for both exists, and is known.

How to find a healthy balance

To solve the challenge between technical uplift versus product feature development it is important to accept that there needs to be a balance of the two at all times. Rarely if ever, will a team need to focus 100% of their effort on one or the other, nor should you want a team to due to the reasons discussed above. As with most aspects of software leadership there isn’t a single approach that can be taken to achieve this outcome. However, the below approaches act as guidelines that can help ensure a balance between technical uplift and product feature development.

Clarify and make clear responsibilities

It is important the software team is responsible and given ownership for two distinct areas. The first being how a feature is solutioned. Software developers are the closest to the code, they understand the impacts different solutioning decisions have on the maintainability and scalability of the codebase. Ensuring software teams own solutioning, it avoids non-technical individuals outside of the team who are less qualified making fundamental technical decisions that could be detrimental to the health of the platform. As part of solutioning, teams should always gather input from relevant stakeholders but this is purely in a consultative capacity. This will also reduce the potential of corners being cut in solutions that normally always results in incurring technical debt.

The second is owning work effort. The software team undertakes the development, testing and deployment of work items, thus are the only ones qualified to estimate the work effort required. Is it impossible and naive to believe a stakeholder can define the work effort required by the team when they do not understand the low level intricacies of the platform. Stakeholders are in their right and should share constraints that may be related to compliance, marketing deadlines or similar with the team. If a stakeholder attempts to define work effort and commit a team to it, as a software leader you need to clearly set expectations that they do not have the relevant expertise to make this decision and that it is up to the team to own work effort estimation. It can be necessary to communicate this message with senior leaders across the organisation, while keeping individuals honest when noticing it occurring.

Where a stakeholder may get involved in conversations is around scaling back feature scope to reduce work effort required if there are legitimate time constraints. By allowing the software team to own work effort estimation you are ensuring that non-functionals are taken into account, that technical unknowns are accounted for, and that the team will solution in line with the software team's target state.

Making technical uplift visible

If technical uplift is not documented, not prioritised and not made visible, team's will always struggle to make progress in it. It would be like walking up an escalator in the wrong direction, the amount of additional effort required is considerably more. Teams wouldn’t and shouldn’t start work on a new product feature without first understanding the outcomes, the priority, defining relevant user stories and documenting a solution. Why should technical uplift work be any different? Documenting technical uplift involves the team defining their most important initiatives, determining the value, prioritising them relative to each other and then work effort estimating them as a team. Try to focus on the immediate top 10 technical uplift initiatives compared to hundreds to avoid overwhelming not just the team but the wider organisation. With technical uplift documented it can now have an opportunity to be discussed and prioritised alongside other priorities coming into the team. It is no longer a hidden list of vague work items in the minds of people within the team.

Justifying technical uplift initiatives smarter

Outside of making technical uplift visible, the other single reason why it can struggle to be prioritised comes down to an inability to justify it in a way that is understood by the organisation. As a software leader you are responsible for being the voice of reason and support when it comes to prioritising technical uplift. Your role needs to understand how the organisation justifies and prioritises initiatives so you can apply the same approach to technical uplift. Below are three common ways organisations prioritise:

• Return on Investment (ROI):
• ROI = total estimated value / cost to implement
• Cost to implement includes all costs associated to develop and maintain including people costs, infrastructure costs, license costs etc..
• Competitor feature parity.
• Cost of Delay (CoD) is the cost to the organisation of not implementing the feature by a certain point in time. This may be lost revenue, compliance fines or lost customers due to a competitor moving faster.

Organisations will quite often use a combination of prioritisation methods as they mature to ensure a more complete justification. By understanding and applying the same justification to technical uplift initiatives it creates a level playing field allowing apples to be compared with apples.

Let’s explore a simple example using ROI as the only method to prioritise both a technical uplift or product initiative across an organisation. The product initiative will bring $240,000 of profit in the first year, at a total work effort cost of $75,000 (which equates to three software engineers for three months earning $100,000 a year). There is also a yearly cloud infrastructure cost of $12,000. ROI for the first year is calculated by:

• ROI = total profit / total cost
• ROI = $240,000 / ($75,000 + $12,000)
• ROI = 2.75

This provides an ROI of 2.75.

The technical uplift initiative will deliver $420,000 of savings by deprecating a legacy platform reducing the need for a small team currently supporting it. The total work effort cost is $100,000 (which equates to 2 software engineers for 6 months earning $100,000). ROI is calculated by:

• ROI = total profit / total cost
• ROI = $420,000 / $100,000
• ROI = 4.2

This provides an ROI of 4.2.

Without taking into account any other prioritisation approach it is clear that the technical uplift initiative provides a higher ROI to the organisation and should potentially be prioritised first.

It is also within your best interest to think carefully about the real costs of managing platforms that technical uplift will simplify and improve. If an initiative is wanting to automate deployment pipelines for a specific platform, it is valuable to understand the costs in maintaining the existing manual deployment processes. You may have four teams spending three hours each week manually releasing code. Over the course of just one year the team would spend $31,200 worth of effort manually releasing. This cost will continue to be incurred every year until the deployment process is automated. The cost of manually deploying also takes precious capacity away from developing new product features. When describing impacts and value in this way, it becomes even easier to rally support from product management as they are selfishly (and rightly so) focused on delivering more product features, faster.

Finally, it is in your best interest to coach software leaders within your team on these prioritisation approaches. This will result in many of the justification and prioritisation conversations being able to happen directly within the team and avoid the need for your role to become involved in every single one of them.

Coupling technical uplift with product features

Sounds simple right? If your organisation is product led, there will be a never ending list of new product initiatives in the backlog. One of your responsibilities of a software leader is to continually look for opportunities and synergies between technical uplift initiatives and new product initiatives. By coupling a new product feature with a relevant technical uplift improvement that resides in the same area of the codebase, it can often reduce effort around testing which creates efficiencies when compared to delivering them both in isolation.

For example, there may be a product feature to implement an additional payment provider to the customer. Within the technical uplift backlog there could be an initiative to improve the level of unit testing that exists within the platforms payment service. There is a clear relationship between these two items of work. In terms of efficiency, there is a benefit to increase the unit testing coverage within the payment service while adding an additional payment provider. Not only do these two initiatives reside in the same area of the codebase, but the work effort in completing them together is also less than the sum of both their work efforts in isolation. This is a result of the effort required to test the platform's payment implementation can be performed just once, not twice. Secondly, the software developers will already be familiar with the payment section of the codebase thus being more efficient, rather than context switching back at a future point in time.

Another example may revolve around the need to support demand in customer growth which requires introducing additional servers into the rotation. The software team also has a technical uplift initiative in the backlog to move all cloud infrastructure into code. Taking a short term tactical approach would see the team simply add an additional server manually into the rotation pool. However, this wouldn’t move the software team any closer to their target state of infrastructure as code. An approach could be to implement the additional server as infrastructure as code, but manually add the server into the rotation. This provides the benefit of meeting the product requirement but also aligning a portion of the work to the software teams target state without re-implementing the entire load balancing capability as code. Of course, if it is possible to also move the load balancer to infrastructure as code, it should be considered.

Identifying synergies between technical uplift and product initiatives has been one of the most successful approaches I have been able to follow to ensure a healthy balance.

Larger technical uplift sometimes requires a project

In some instances, a technical uplift initiative is simply too large in work effort to be coupled into a product initiative. A fundamental goal of software teams is to ensure they release small and release often. This implies avoiding weeks or even months of code not being released into production. When a technical uplift initiative requires considerable work effort to see it through to completion, it needs to be treated as a project. This involves defining clear outcomes, measures of success, documenting high level scope usually as user stories, estimating work effort and a justification aligned to the organisation's process.

Using the technical uplift example of implementing an automated build pipeline, the justification may look like:

• The current cost to the organisation of not implementing
• Four teams each undertake one release every week.
• Each release costs four hours of work effort.
• As each release is after hours it also incurs three hours Time in Lieu (TIL).
• This sums up to 1,456 hours a year releasing features.
• This equates to $72,800.
• Total cost in work effort to implement is 988 hours
• This equates to two software engineers for three months.
• The total work effort costs $49,400.
• By entirely automating the platforms build pipelines, after the first year there will be a cost saving of $23,400 and then $72,800 for subsequent years.

That is a very persuasive justification as this initiative pays for itself after just 9 months. Taking it one step further, as the teams are now able to release new product features with zero manual effort it enables smaller feature releases more frequently. This reduces production deployment risks while delivering value add features to customers faster than ever before. I would challenge you to find any product role who wouldn’t support this initiative within the organisation.

Ensuring a combined organisational roadmap

In many organisations it can make sense to have a separate technical uplift roadmap and product initiative roadmap. This can support a more efficient planning process within specific teams as these roadmaps are often owned by different leaders. However, at an organisational level when organisational priorities are published, it is imperative to have a single and aligned roadmap that includes both technical uplift and product initiatives prioritised side by side.

Breaking down larger technical uplift initiatives

The larger the work effort is for an initiative, the harder it is going to be to justify and prioritise. Organisational leaders usually struggle to support large initiatives as their value won’t be realised for a considerable time into the future. Prioritising a six month work effort product initiative is challenging enough, let alone a six month technical uplift initiative. As a software leader, you need to be continuously looking for ways to break larger initiatives into smaller work items that can be delivered into production sooner.

For example, take the technical initiative to implement a new organisational wide logging and monitoring platform that has a total work effort of seven months. By breaking it down into smaller work items as seen below, the effort required to justify is greatly decreased, risks are reduced and work items that can run in parallel may become more clear.

1. One sprint to research and document a solution.
2. Three sprints to build out the base logging and monitoring platform.
3. Two sprints to upskill and train all software teams.
4. Three sprints to integrate logging into the first platform.
5. One sprint to implement monitoring into the first platform.
6. ... Repeat steps 4 and 5 for each additional platform.

Always focus on finding the smallest item of work that can be released into production that still adds value to the organisation.

Definition of Done

A Definition of Done (DoD) is essential for every software team to define and proactively adhere to. The purpose of a Definition of Done is to improve the overall quality of the capabilities that the team deploys into production. Quite often a Definition of Done includes specific non-functional requirements (NFRs) that a team values, which may include:

• Automated testing exists for each feature.
• Solution and code has been peer reviewed.
• Documentation has been created or updated.
• Monitoring has been implemented to ensure observability of all critical paths.
• Product owner has reviewed and signed off on the new capability.

A Definition of Done does not reduce existing technical debt, however, it plays a part in reducing new technical debt being created which would otherwise need to be paid back in the future.

TL;DR

• The decision between technical uplift and product initiatives shouldn’t be a binary decision. An organisation needs to find a healthy balance between the two to ensure platform scalability, new product development and retention of team members.
• Technical uplift initiatives need to be documented, prioritised and made visible to the wider organisation otherwise the team will always struggle to make progress.
• Continually look for opportunities to couple technical uplift with new product initiatives. This will encourage efficiencies by reducing testing time and reducing context shifting the software team may face by tackling both initiatives separately.

This blog post is taken from chapter 7 of my book "Leading software teams with context, not control" - I hope you enjoyed it. If you did, check out my book that has 22 other chapters on leading software teams on Leanpub as well as other online stores like Amazon in eBook or print format.

Read More

I've written a book about leading software engineering teams

Ten months ago I set myself a one year goal to write a book on leading software engineering teams. This books purpose was to document the practices and initiatives I followed while leading software teams. It was to provide myself with a reference model to refer back to and reduce the cognitive load required within my day to day role. What started off as a casual few hours a week planning and firming up the books chapter, rapidly turned into 3+ hours every night researching, writing, rewriting, deleting and writing some more in an effort to complete this side project before our first baby was born. I didn't exactly make the 9 month deadline, but published v1.0.0 three days later. The book is titled "Leading Software Teams with Context, Not Control" and can be purchased from Leanpub as well as other online stores like Amazon in eBook or print format.

Why this book was written

As a software engineering leader, the scope of your role is extensive. You have many competing responsibilities and priorities that need to be balanced to ensure you and your team are as effective as possible. These can include providing architectural direction, driving peer to peer collaboration, ensuring cross-team alignment, motivating teams with purpose, supporting team members' career progression, or perhaps helping remove blockers and impediments. All of these efforts work to create a specific culture within a software team that aims to improve effectiveness, engagement, and retention.

I wrote this book for software leaders who are responsible for leading teams. More specifically it focuses on approaches for leading multiple software teams whether that is directly or indirectly through leadership roles reporting into your role. There is a level of unique complexity that comes with leading, aligning and supporting multiple software development teams. This book aspires to provide you with helpful and reusable approaches that can be leveraged to bring about a greater level of efficiency into your role as a leader. There are many books written around leading teams or leading people, this book takes a lens of what specific practices and initiatives you should be investing your time into when leading technical software teams.

Regardless of the size of your software team, if you find yourself needing to better balance both the technical and people aspects of leading teams, or guidance on initiatives you could be running to improve team alignment, effectiveness and engagement then this book is written for you.

What's in the book?

The book comprises of 23 chapters that discuss a broad range of initiatives you can run when leading software engineering teams. These range from baselining a software team to effective software engineering metrics to crafting an experimentation culture. The book is broken into 3 parts:

• Part 1: Creating alignment
• Part 2: Leading teams
• Part 3: Uplifting team culture

Each chapter has a loose structure of explaining the topic, talking to why it is important within a software engineering team and different approaches you can use to implement within your own team. Most chapters include multiple exercises that you can adopt into your organisation, as well as the occasional story around specific experiences I have had while leading teams in my previous and current roles.

Interested in more insight to exactly what is in each chapter just incase it tempts you to pick yourself up a copy? Here it is...

Part 1: Creating alignment

1. Baselining a software team
   All the thing you need to do to understand the current state of your software engineering team. It talks to technical and team cultural measures and techniques to determine a teams baseline.
2. Defining a software team target state
   A software target state is the technical and non-technical aspirations of the team that are flags on the top of the hill for you and your team to continuously climb towards. Learn how to define a software target state for your team.
3. The software engineering roadmap
   A software engineering roadmap is a visual representation that defines a team's pathway to achieving their target state. This chapter explains the importance and how to implement one.
4. Effective software team metrics
   Metrics within software are measurements that are put in place to keep you and your teams honest, accountable and continuously improving. Learn about what makes good team metrics, as well as metrics you need to avoid.
5. Importance of collaborating on team goals
   Setting goals for your team or team members does not need to be an overly time consuming exercise, although it does need to align to your team target state, roadmap and team metrics.
6. Balancing reactive versus strategic work
   Getting stuck in the weeds is all too common for software engineering teams, learn about strategies to better balance the time you spend on strategic based work items.
7. Balancing technical uplift with product development
   The decision between technical uplift and product initiatives shouldn’t be a binary decision. Discover approaches to find a healthy balance between the two to ensure platform scalability, new product development and retention of team members.
8. Introducing a new technology
   As a software leader, you are accountable for ensuring relevant new technology is being adopted within your team at a healthy and manageable pace. This is compared to implementing too many technologies too quickly and running the risk of losing great software developers from technology change fatigue or cognitive overload due to overly complex platforms.
9. Platform SLAs
   Discover SLAs that add value to a platform, as well as important items to consider when implementing SLAs for your software teams platforms.

Part 2: Leading teams

1. Effective 1:on:1s
   1:on:1s are weekly or fortnightly catch-ups with each of your direct reports, that provide an opportunity for you to listen, provide guidance, coach, listen more and support them within their role and future career aspirations. Find out about approaches to make the most out of 1:on:1s within your team.
2. Continuous performance feedback
   Performance feedback within software teams should more than a once yearly exercise that is orchestrated through the organisation's HR department. There are many opportunities to provide constructive feedback to your team every day of the week.
3. Impactful position descriptions
   Position descriptions are short (no more than 3 pages), well formed documents that clearly articulate the impact a role has, where it sits within the organisation and breaks down the key responsibility areas of that role. Discover how to craft position descriptions that create a sense of excitement and motivation within a role that is genuinely valued within the organisation.
4. Candidate centric interviews
   Understand what candidate centric interviews are and how they build trust between the interviewer and the candidate which results in them being more genuine about their experiences, concerns in the role and their career aspirations. While at the same time becoming more invested in the role within the team.
5. Onboarding effectively
   Effective onboarding should include a combination of discussions, introductions, workshops, documentation sharing and mentoring to support new starters in becoming a motivated and effective team member. This chapter explains the different phases of onboarding to focus on within your software teams.
6. Software team structures
   Learn how to implement ‘just enough hierarchy’ while coupling it with small team sizes of seven or less, to dramatically reduce the blast radius and impact when an individual chooses to move on from the organisation. 
7. Career pathway framework for software teams
   A software career pathway framework links together roles to represent different pathways of progression an individual can follow to advance their career within the team that aligns with their skills, experience and motivation. It is not a trivial task, however this chapter aims to provide some key learnings to fast track your own implementation.

Part 3: Uplifting team culture

1. Context over control
   It is in the title of this book, and this chapter explains how a context over control approach allows software leaders to lead vastly larger teams and projects when compared to a micromanagement approach.
2. Engaging team meetings
   As a software leader you are accountable for ensuring weekly team meetings are set up, are engaging, have the right amount of energy and bring value to as many individuals within that session as possible.
3. Team health checks
   Team health checks usually consist of six to ten questions that focus on technical, team and communication practices that each team discusses and rates every six to eight weeks. Understand what makes health checks valuable and approaches on running health checks within your teams.
4. Building a culture of learning
   A software team that is built around a culture of learning allows its members to learn in all aspects of their role. Learn about how building a culture of learning can be achieved at no financial cost to the organisation.
5. Crafting an experimentation culture
   Software teams that embrace an experimentation culture have a more maintainable technology stack, incur less technical debt, and are thus able to iterate faster on developing and releasing new capabilities. Discover approaches to encourage experimentation in every aspect of your teams day to day.
6. Software engineering working groups
   Software engineering working groups involve a set of individuals working together to build a center of excellence around a specific topic. This chapter explains different approaches of implementing working groups within your organisation.
7. Running a software team hack day
   Running a hack day allows your teams to take a break from the day to day and collaborate together on solving real software engineering problems being faced. Learn about a high level structure and run sheet you can use to run your very own hack day.

Although this goal can now be ticked off my list, I'm looking forward to many future iterations as I evolve my ways of running software engineering teams. If you would like to check out a free sample, you can download it over at Leanpub. eBook formats are available on Leanpub, Amazon, Google Play and iBooks. Print copies can also be purchased from Amazon.

Read More

How to bulk reset your Reddit upvote history

April 3rd 2020

Ever needed to bulk reset your upvote history for a subreddit? Yes, it is a bit of a random topic. However, I found myself in this situation recently and there wasn't a way to do so using Reddit's built in capabilities. A simple piece of Javascript came to the rescue!

Disclaimer: This solution is coupled to the markup of the current Reddit website. So will only be functional until Reddit changes their markup in the future.

Start by navigating your browser to:
https://www.reddit.com/user/dionbeetson/upvoted/

Then open up your developer console (F12). Click on the console tab.

The javascript code

/**
 * Function to clear votes for a specific subreddit
 */

let clearVote = (subReddit) => {
    let clearedCounter = 0;
    let anchorsFound = document.querySelectorAll("a[href$='/r/" + subReddit + "/']");

    for (var i = 0, l = anchorsFound.length; i < l; i++) {
	let anchor = anchorsFound[i];
	let post = anchor.closest('.Post');
	let button = post.querySelector("button[data-click-id='upvote']");

	button.click();
	clearedCounter++;
    }

    console.log('Cleared ' + clearedCounter + ' upvotes from ' + subReddit);
};

// We need to continually keep scrolling to the bottom to load more history
let scrollToBottomCounter = 0;
let interval = setInterval(() => {

    if( scrollToBottomCounter > 300 ) {
        clearInterval(interval);
        clearVote('Bitcoin');
    }

    window.scrollTo(0,document.body.scrollHeight);

    scrollToBottomCounter++;
}, 1500);

// Call clear vote for the subreddits you want to clear your upvotes for
// EG: this is the name of the subreddit that you can see within the UI that looks like r/CryptoMarkets/
// However you simply include the subreddit name and not the starting 'r/' and trailing '/'
clearVote('InstantRegret');
clearVote('RoastMe');

// You can call clearVote as many times as you require.

How to run the script
Now, after adding a 'clearVote' function call for each subreddit you want to clear upvotes for you can paste this script into the 'console' within your browser and the script will simulate a user clicking the upvote button for all of your upvote history.
Enjoy :-)

Read More