Why you want this and how to become one
TL;DR
Once you are replaceable, you are free to start new initiatives, explore new technologies, solve the next complex problem which will make you happy and interested to stay at your job. Your organisation has a lower risk of discontinuity and can benefit more from your expertise. To be a replaceable developer, you need to
- deal with all the relevant unshared software that you have created in solitude;
- document knowledge about relevant processes.
Challenge
Over the years, as a developer as part of an organisation, you will work on many different software projects, learn a lot about the business and processes and will have created many software artefacts (packages, libraries, applications, services, architectures, infrastructure, …).
If you are a more senior developer, typically, you will have created software that might be quite clever in solving a particular complex problem or introduced a bit more of that complexity because you wanted a solution that would fit many similar problems in the future (YAGNI [1]). And because most other developers just use your great software, they will probably only give you feedback (bugs, suggestions) but less collaboration time or even coded changes.
Untouchables
If this is the state of your software, you can now add your complex solution to the “List of Untouchables”. This is a list of work that nobody else has deep knowledge about. Other developers might not even know that you created it. The location of the sources may also be a mystery to them. It is a solution for which each of the following questions are probably answered with “Do not have it; did not need it”.
- What are the requirements that are met by this software?
- What design decisions were made?
- How do you build, test the software?
- Where is the documentation?
- Information about the internals?
Irreplaceable
Over the years, you may have collected many entries to the “List of Untouchables”. Some are small, some are bigger. Some are technical masterpieces, some deal with complex processes (e.g., data flows). On the one hand, you should be proud of creating this list of beautifully crafted software; it solved problems the organisation faced in the past. On the other hand, you are now an irreplaceable developer and it is time you realise that this is not a good thing for you or your organisation. Let me explain why.
No more time left
Since you are solely responsible for the software on the list, all feedback, bugs, requests, questions or even annoyances will reach only you. You are the sole designer, coder and maintainer of the software. Only you can answer those questions, can make changes and are able to test it. This will eat up your valuable time, and will take away the focus you need on other, new complex tasks. Suddenly, you are the bottleneck to others who want to complete their feature that requires a fix or extension to your software. Or you have to explain again to the new team members how your software must be used. The longer your list of untouchables, the more time you will have to spend on keeping your software alive and used by others.
No more growth
Because you spend much of your time helping others to achieve their tasks, you will no longer have the time to explore other technologies, try out new techniques, be invited to join other teams, learn new skills, read tech news, learn from others, solve new problems. In the extreme case, all you do is maintain your legacy. You will get bored; this is not good for you. You will start looking for another job; this is not at all good for your team and organisation.
Strategies
Clearly, it is beneficial for everybody that you recognise the situation you are in and start making changes. To start, you need to be honest and write down your list of untouchables. Ask your fellow developers or even your manager to get a complete list. Make sure it only includes the complex, hard to understand artefacts; the simple and trivial ones do not have the negative impact as described. Once you have that list (no order needed), you will decide which of the following strategies can be applied to each list entry.
S1: Sharing
You will start sharing your knowledge about that software with other developers. The goal is to gain confidence that any of those developers has sufficient knowledge to get around the software and is able to self educate further. It should provide a basis to get more advanced/detailed knowledge without further assistance. In the section “Knowledge Sharing”, I will discuss some methods on how to achieve that.
S2: Keep it like it is
The software has been marked as deprecated and therefore it does not make sense to put any effort into it. Because it is deprecated, no new features requests will be accepted. The software is in maintenance mode. Maybe bug fixes are still needed; you will have to make them yourself. Communicate that it is end-of-life. Consider helping the users of your software to migrate to the new solution.
S3: Stop using it.
Variation of S2 but a more radical decision. This strategy can be applied when there is already an alternative solution in place and no one is actually using it anymore. Shutting down the application, removing it from any documentation, archiving the software are possible actions to be taken.
S4: Rewrite the solution
Your software is written in a programming language only you can understand and nobody else wants to learn it. Or it uses a very rare or old framework for which no documentation or usage is found on the internet. Or nobody wants to touch it because the code quality is simply bad (not conforming to standards). Because no one can grasp the source code, finding bugs or creating change requests by other developers will not happen. But the software is an important part of the architecture or business process so it is necessary to replace it by another solution. It is probably best to aim for the broadest possible basis, i.e., as many developers as possible (possibly the whole team) and a language that is familiar to many developers.
S5: Untangle
Your software has grown to an unmanageable size. Too many responsibilities have been put in the software in all the years. No one other than yourself is able to have the complete picture of its design and implementation. Parts of your software may already be dead code. It is time to decompose your software into a group of smaller solutions. Each of those solutions may have to be added to your list of untouchables for which you need to repeat choosing a strategy (S1..S4).
Knowledge sharing
Sharing your knowledge with others has two major benefits to you. First, you will learn how to communicate about your solution. Designing and creating a solution is very different from explaining it (verbally or written). You want to improve on those skills because for the next problem to be solved by your team, you will be better in “selling” your solution to them. Secondly, by sharing knowledge you will have developers that can help you solve problems with your software, explain its workings to others, troubleshooting issues and you can delegate certain new features to them. Many methods exist to share knowledge about software and applications to other developers or users. Surprisingly, I was able to list methods which I consider “good” and “bad”. Let me start with the methods you want to avoid and end with those I suggest you remember.
Bad methods
Email, Messenger (Slack, Signal, Whatsapp)
Do not write explanations, requirements, sample code, etc, in email conversations. Even if others are included in the conversation, most likely you will not find this information again and it will not be accessible to future team members. Better is to refer (link) to some documentation that is shareable and can be maintained (bug tracker, wiki, knowledge base, …).
Verbal one-on-one conversation
Talking to each other seems like an easy and convenient way to share knowledge and get immediate feedback. However, you only shared it with that person. Others that were not part of that conversation will not be aware and might ask you the same questions later. Better organise a meeting and invite more people to the discussion. And if you had such a conversation and realise it might be of value to others then write down what you have discussed or decided in a shareable document. Could be a Wiki page, an Issue ticket, a set or presentation slides etc.
Good methods
README.md, Example code
Include a README with the source code of your solution that explains what problem this software is solving and how it works. Write some example code so that users can start easily (your users will not read your tests). For project contributors, add a section that explains how to build and test your solution. If your project is set up with a Continuous Integration tool (CI/CD) then you need to document that too. Also include links to any tools that are required for these steps.
How-to articles, Wiki pages, Troubleshooting guide
If you are being asked questions about the usage of your solution consider answering it by writing it down in a How-to first and send the person the link for both review and to solve his/her problem. That way you will build a set of shareable documents that anybody can refer and contribute to.
Presentation
Putting together a presentation requires a bit more work but it is very effective and efficient to its receiver. Using a presentation, you can tell a story, give examples of problems that it solved and highlight the features etc. Make sure others can contribute to this presentation so do not use presentation software that is operating system dependent, i.e. use a browser based (cloud) tool.
Screen cast
If you are feeling very confident and want to show the software or solution in use you could create a recording of a tutorial. If you are planning to show actual coding then separate the video from the audio: first record the video as you are typing, clicking, dragging etc. Secondly, narrate your recording with your comments. Your viewer will have more focus on what is shown and get less distracted by all the unneeded noisy comments and uhs. The downside of using a recording is that its contents is not searchable (yet). Also avoid creating long recordings ; a maximum of 12 minutes for a topic is recommended.
Diagrams
Visualising how your software works or is designed is a powerful method for sharing knowledge. Preferably use well-know abstractions and symbols in your diagrams so that diagrams do not need too much explanation. Add a short symbol explanation list in some corner of your diagram or stick to actual standards such as ERD or UML. Also make sure that the lines/arrows between the symbols are clear. Examples are a data reference, a communication, data flow direction, request and response, dependency.
Summary
Making software is a creative process of solving a problem. Problems can be easy to solve, the complex ones will require more time, thought and experimentation. In the beginning, complex solutions start out as a potential entry to the list of Untouchables. At some point during the evolution of your software, you should realise it reached a state that it can be used by other developers in other programs or processes. At that moment, you should start spending time on making your product understandable and accessible to contributors. Whatever content you produce to share knowledge, make sure other developers can contribute to it such as changes, comments, additions.
Once all the software that you have created for your organisation is known to others, is well documented and understood, then you will feel the freedom to move on in any direction you want. You can switch teams, dive into a new technology or even become a manager. Becoming replaceable will make you a happier person and will contribute to a healthy culture in your development organisation.
[1] YAGNI: you aren’t gonna need it