DEV Community: Erik Melone

Pull Request Descriptions should not be Optional

Erik Melone — Sat, 02 Oct 2021 18:19:52 +0000

Pull Request descriptions are documentation too. In fact, they may be one of the more efficient types of documentation. Pull Requests are unique in that they maintain a record of how our code changes over time, combined with the ability to attach text in the form of a description to them as well. This ability to attach a large amount of text to an increment of code changes is not something that we see anywhere else in our ecosystems as developers. We can add comments to our code, but long in-depth explanations shouldn't belong in our code.

By building a culture of writing out detailed PR descriptions, we can enable Pull Requests to be yet another resource available for a developer. Ever see a line or block of code that is slightly confusing? You can navigate to that line in your GitHub repository and view the Git Blame for that particular line.

Notice that in addition to detailing which commit the change belonged to, it also links the Pull Request! If this Pull Request has a well-written description, then this might clear up confusion on this particular line of code.

Most people likely aren't used to using Pull Requests in this type of way, likely because if they tried to they would be met with a blank description 95% of the time. But, if you and your team get into the habit of writing descriptions, you'll be able to reap the benefits of a documented history of your codebase.

The Anatomy of a good PR Description

Hopefully by this point, I have convinced you that PR descriptions are important. And like with all documentation, the truth is that writing something is better than writing nothing at all. If you are in a time crunch and need to publish a PR as soon as possible, then even a few lines explaining the change are better than nothing. By the same token, our documentation gets better when we approach writing with a bit of strategy.

In GitHub, you can use Markdown in your PR Descriptions to help format your thoughts (yet another reason why You should learn Markdown). Let's take a look into how I like to format my Pull Request Descriptions.

Link to Task

If you're working in any team, chances are you do some type of task management, be it in Jira, Asana, Trello, etc. Therefore the work you are doing in any given PR has some logical counterpart on your Sprint Board. The very first thing you should type in your PR Description is the following:

[Link to task.](https://myteamsjiraurl.com/mystory)

This now creates a link between the task management system and the actual code itself. Whenever someone goes to review this PR, they can go view the relevant story to get an idea of what exactly this PR should be accomplishing.

Linking the story also gives additional context to those who might be viewing your PR from 6 months in the future. If they see a code change they are trying to find out more about, having the context behind the work itself is incredibly useful.

Background

After linking the Task URL, I oftentimes add a section that gives some detail into the reasoning behind my changes. Perhaps you had to choose between two solutions - this is a place to justify why you chose the solution that you did.

Another example is if you have some complex code logic. This section would be a great place to explain that logic - it helps both your PR Reviewers and anyone who comes back to this PR looking for additional information.

In some cases, writing a Background might be unnecessary. For example: if the change is a routine vulnerability remediation, then likely not much explanation will be needed. A link to the task from the previous section will be enough to explain the contents of the PR.

Determining when it is necessary to write a Background, and how to write said Background, is a super important skill that can take your PR descriptions to the next level.

Changes

A Changes section is necessary for a PR description. It also happens to be a fairly easy section to write - just make a bulleted list of all the changes you have made.

Go through your Pull Request and write one-liners for the high-level changes you have made. Here is an example:

- Added the business logic for onboarding a brand new user
- Refactored the existing user login code to share some components with the new onboarding logic
- Added some unit tests for the user onboarding scenarios

This Changes list can be super simple - it is meant to be a snapshot of the work you've done in this code increment. Again, this just increases the visibility and readability of your work.

Doing this also forces you to proofread your code as well. This is a valuable exercise to help you catch any minor typos or mistakes you have made before sending it off to your team. It also forces you to go over the code you wrote - oftentimes when I am writing my Changes list, I see a piece of code that I wrote and think of an even better way to rewrite it and optimize it.

Screenshots

Depending on the type of work you do, adding Screenshots might not be applicable. However, if you're doing any type of Frontend Web or Mobile app development - screenshots should be an absolute must.

Adding screenshots can show your reviewer what the change looks like in your app. This saves them from having to check out your branch and build the app themselves to view your changes.

You can also use these screenshots to show a Product Manager or Designer the work that you have done - I've found that they always greatly appreciate that.

Another option, though more time-consuming, is to record a video. While this may not be necessary for all changes you make, sometimes recording a video for big feature changes is helpful.

Use GitHub PR Templates

A large part of writing PR Descriptions can feel very Boilerplate-y. This is why learning to leverage PR Templates is super helpful. If you're using GitHub it is super easy (I am sure other Git repository hosts make it easy as well).

For GitHub, just follow the instructions here. Here is an example template that I use in all of my personal projects.

[Link to Task.](https://www.notion.so/XXX)

## Background

If applicable, provide some background about the choices you made in this PR.

## Changes

- ...

## Screenshots

If applicable, provide some screenshots below.

## Review Checklist

- [ ] Proof Read Code
- [ ] Write PR Description
- [ ] Request Review

This will render into the following when I open a PR:

Notice it contains the 4 pieces we've talked about here, in addition to a Review Checklist. I add this checklist to keep me honest and make sure that I proofread my code and write a description before I ask anyone for review. Feel free to edit this template to suit your needs.

Ultimately, writing PR Descriptions shouldn't feel like a drag. Make it a point to spend no more than 5 minutes writing your description before submitting it for review. If you can get an entire team to follow this methodology, you might be surprised to see the impacts it makes.

3 Ways you can ask Better Questions as a Junior Developer

Erik Melone — Sat, 25 Sep 2021 14:23:52 +0000

Asking questions is literally the first piece of advice anyone gives to a brand new developer, and there is a good reason for this. I cannot emphasize the importance of utilizing your teammates as resources to help you learn. The whole point of working in a team is so that teammates can help each other out. If you aren't constantly asking questions within the first couple of months on the job, you are not taking full advantage of the resources around you.

There is a caveat to this point that isn't talked about enough: not only should you be asking plenty of questions, but they should also be the right questions. Before I go any further, I want to emphasize that I am not trying to scare anyone out of asking questions. I don't mean you should be worrying about whether your question is a "stupid question" or not - it is perfectly acceptable to ask a "stupid question". It is also perfectly acceptable to ask for help. Instead, I believe there are certain ways to phrase typical questions that can help better set you up for success. Let's explore a few examples.

Don't Ask: "Can you explain <insert business process here> to me?"

Do Ask: "Do you have any resources about <insert business process here> that can help me learn more about it?"

Chances are, there is some resource that already exists to explain the business process to you - and this resource likely will be a lot more thorough than the answer your teammate will have to come up with on the spot. If this resource still doesn't help you understand everything you need to know, then you can ask follow-up questions for further clarification. You now also have a bookmarkable page that you can refer back to whenever you need a refresher. Win/win!

Don't Ask: "What's wrong with my code? Can you fix it?"

Do Ask: "I am having issues with my code, I have tried x, x, and x. Do you have some time to rubber duck this?"

It is normal to ask another team member for help on your code, this is another one of the whole points of working in a team. However, blindly asking for help is disadvantageous for both you and your teammate:

If you get into the habit of immediately asking for someone to fix your code as soon as it breaks, you'll never gain the skills to debug complex problems on your own
From the teammate's perspective, getting asked to "fix someone's code" is a very frustrating experience. You then have to spend time understanding all the context of the code before you can even begin to debug.

The Do Ask question in this scenario does a few things:

By forcing yourself to wait until you've tried a few different approaches to your problem, you force yourself to think more critically. You might even stumble upon a solution and not even have to ask for help. This is the best way to learn!
If you don't stumble across that solution, then at least you can tell your teammate what you have attempted before asking them for help. This reduces the amount of time your teammate has to spend debugging the problem, hopefully allowing them to figure out the issue even sooner.

Don't Ask: "How do I do this task?"

Do Ask: "I am a bit confused about this task. Do you have any suggestions on how to get started?"

As an inexperienced engineer on a new team, one of the scariest things is getting assigned that first Jira Story and having no idea how to do it. Again, this is the point where I reiterate that I am not trying to discourage junior engineers from asking for help, I just think there is a better way to go about it than straight-up asking for help.

Say you ask "How do I do this task?". Your teammate will then hop on a call with you and guide you step by step through the process. Or worse, they'll do it for you while you watch. There is some value to this, but there is even more value if you are given the opportunity to attempt the task on your own before you reach this point. By asking the "Do you have any suggestions on how to get started?" line, you give yourself that opportunity. Your teammate can now start you on the right path, without accidentally doing all the work for you. If you still struggle, then it might be time for that step-by-step walkthrough. But make sure that you are the one doing the work, rather than them showing you by doing it themselves.

Asking questions is one of the scariest things you need to do as a new developer. None of these examples are meant to imply that you should be scared to ask questions - in fact, quite the opposite. They are meant to show you how you can make your questions even better and more useful for you. By thinking a little bit about how you communicate, you can gain way more out of a simple Slack DM. And you might even impress your teammates along the way.

If you liked this article and want to be notified when I publish another, consider subscribing to my mailing list.

Centralize your Documentation with Docsify

Erik Melone — Sat, 18 Sep 2021 14:38:58 +0000

The Importance of Centralizing

Writing documentation in the first place is a great first step towards making the software and ecosystem that you work on better. The next important step in documenting your work is to make that documentation available. If you go through all the effort to write clean and concise documentation but don't publish it in an easily accessible location, then it will be hard to get your audience to even read it. If no one can easily read your documentation, then it is not reaching its maximum potential.

In some cases, for example instructions for setting up a project repository, there is a natural place for your documentation - just add a README.md to the repository. GitHub and most other Git repository management tools automatically render your Markdown when you visit the repository. But what about when the documentation you write isn't about a particular application or repository - where would you put it in that case?

You could just throw it in some random Git repository and share the link, but then that link has a very high likelihood to get lost in Slack DMs or emails. A better solution is to create a dedicated and centralized place to store all documentation. This has many benefits:

It creates a constantly updating collection of resources for your organization. All you need to do is bookmark the site and you'll get easy access to this collection forever.
It eliminates the ambiguity in where to publish documentation. If anyone ever writes a document and has no idea where to publish it, they now have an easy answer: publish it to the centralized location!
It gives individuals an obvious first place to go when they have a question. If your organization has thorough documentation, chances are the answer is there.

Piggybacking on the last point, if the documentation is thorough, then a centralized place for documentation can also help you deal with this scenario you probably encounter daily:

"Can you explain <insert business process> to me?"

When asked this question by a coworker, just respond with:

"You should be able to find it in our centralized documentation. If you read through it and are still confused, I'd be happy to further elaborate."

99% of the time, I never hear from those individuals again.

Getting started with Docsify & GitHub Pages

One of the best solutions for this centralization problem is Docsify & Github Pages. With these two tools, you'll be able to start a website to host your organization's documentation in no time.

Docsify is a tool that dynamically generates HTML files from Markdown files. This allows us to take advantage of all the benefits of Markdown to build a website very easily. To get started, check out Docsify's Quick Start guide. They provide a way to run a local environment so you can edit Markdown files and instantly see the resulting pages that Docsify generates for you.

GitHub Pages is an easy and free way to host your Docsify website. Docsify also has a deployment guide which you can follow to host your documentation site in minutes.

Why Docsify & GitHub Pages?

1. Docsify gives us all of the advantages of Markdown, combined with the ability to customize how your pages render. Markdown is the easiest way for developers to write down their thoughts, and Docsify fully supports the Markdown spec. There are also a variety of ways to customize your website built through Docsify:

There are several configuration options built by the creators at Docsify.
You can provide your own custom themes to customize the appearance of your pages.
Docsify comes with plugin support as well. Check out this extensive list of plugins that are available for Docsify. If you can't find a plugin that accomplishes what you need, they also give you the option to write your own.

2. Hosting with GitHub pages gives you familiar source control with your documentation. This allows us to treat our documentation as we do our code. We can easily collaborate on the same page of documentation, and also have access to the entire history of a document. Additionally, hosting the Markdown files on GitHub allows for an easy review process, leveraging the same Pull Request process we use to review our code. This encourages more collaboration on writing documentation, something that I believe we can do more of as an industry.

3. Docsify is as simple as you need it to be. The flexibility of Docsify makes it very simple, yet extensible. If you just want to write some Markdown and render your pages, Docsify makes that very easy for you. If you'd like to customize your pages, Docsify enables that as well - it supports it. You can choose how deep you want to dive into the Docsify ecosystem.

Advanced Features

There are a few advanced features of Docsify that easily elevate your Markdown files into a full-fledged website.

Sidebar

One of the most useful built-in features of Docsify is the ability to create a sidebar for your documentation site. Better yet, you create the sidebar through syntax you already are familiar with - Markdown! Here is an example of a sidebar that we can define with Markdown:

<!-- docs/_sidebar.md -->

- [Home](/)
- [Learning HTML](html.md)
- [Learning CSS](css.md)
- [Learning JavaScript](js.md)
- [Learning Frontend Web Frameworks](frontend.md)

Having a sidebar turns your collection of Markdown files into a cohesive, navigatable central resource for your organization. It makes all the documents in your repository easily accessible from a nice web interface.

Tab Controls

One of the Docsify plugins I have used the most is docsify-tabs. This plugin allows you to easily build a customizable tab control from Markdown:

<!-- tabs:start -->

#### **React**

Facebook's frontend framework for building reactive, component-based user interfaces.

#### **Angular**

Google's frontend framework for building speedy and performant user interfaces with extensive built-in tooling.

#### **Vue**

Evan You's approachable and versatile frontend framework for building user interfaces.

<!-- tabs:end -->

The above Markdown renders into the following tab-based UI:

This is a very simple way to easily improve the readability of your simple Markdown files, without any additional effort. There are plenty of other plugins that you can bring into Docsify that have a similar effect. I encourage you to look through this list of Docsify plugins to see if any additional plugins will make your documentation even better.

If you liked this article and want to be notified when I publish another, consider subscribing to my mailing list.

How to write clear and concise documentation

Erik Melone — Sat, 11 Sep 2021 14:20:25 +0000

The Problem with our Documentation

We have a problem with the majority of our documentation as Software Engineers: when we do decide to write documentation, it tends to end up overly complicated, full of jargon, and unfocused. We spend hours on end trying to make sure we write the cleanest code possible, yet put very little thought into how we write our documentation.

One way to put more thought into our documentation is to simply spend more time on it. The issue is, at most companies we aren't given the time to do this - good documentation doesn't necessarily produce the short-term results that a business looks for.

Rather than spending time scrutinizing every paragraph and explanation you write, consider the following approach. Before writing anything down, spend 10 minutes doing some planning and determine a baseline and a scope for your documentation. This planning can not only make the writing process easier for you but also help the reader make the most out of your documentation. Let me elaborate.

Set a Baseline

Perhaps one of the hardest parts of technical writing is identifying the skillsets of your audience. You can publish a page to your team or organization, and have no idea who is going to end up reading it. Imagine writing some documentation on a very niche topic that builds upon many other concepts within your team's ecosystem. A seasoned veteran reading this will likely have no issues understanding your writing. However, what if a newbie to the team stumbles upon this documentation and tries to read through it? Suddenly, the documentation has done the opposite of what it has intended to do - the various jargon and implied knowledge throughout your document ended up making the topic more confusing for the reader, rather than less confusing.

A baseline of knowledge is the minimum amount of information required to understand the information you write in any given document. Before even beginning to write documentation, write out a bulleted list of all topics that you will assume are known by your audience. Place this bulleted list at the top of your page in its own section - perhaps label this section as "Baseline".

Here is an example baseline I would set for a page on learning Redux:

# Starting out with Redux

## Baseline

- Knowledge of React, particularly in: components, state, lifecycle, hooks
- Functional programming concepts: pure functions, side effects
- Immutability

Defining a baseline at the top of your page does a few things.

It makes it easier to write. By defining a baseline, you define a minimum set of knowledge that is now implied. You no longer have to describe any details of any of the topics you listed within the baseline. Technical jargon now becomes more helpful rather than confusing - I can now use the term "pure function" when describing a reducer in my Redux page, and be confident that the reader will know what that means. This allows me to be more concise.

It makes it easier for the audience to understand your writing. Now that there is a clear expectation set at the top of the page, a reader can evaluate how much they already know. They can choose to read up on these topics before continuing on with this particular document, rather than blindly diving into a piece of documentation. Once they are ready, they can come back to this documentation equipped with the knowledge they need to read through your explanations.

It identifies gaps in your ecosystem's documentation. Now that you have written a baseline, you can go through each item and link them to other resources and documentation to help the reader learn. This has the obvious benefit of making more documentation accessible to the reader, but it also helps to identify certain subject matters that are lacking in documentation. Note these subject matters down as future candidates for more documentation.

Set a Scope

Certain pieces of documentation try to cover too much at once. It is easy to separate topics at a macro level. Consider writing a set of documentation that will cover the entire animal kingdom. An obvious place to separate pages of documentation is between the different animals. We will write a separate page for a Bengal Tiger and another for the Northwest African Cheetah. This distinction is clear, but will we really be able to contain all information about the Bengal Tiger on one page? Likely not. We could write a page on the hunting habits of the Bengal Tiger, and another on their habitats. Even these topics might be too broad. Separating topics on a micro-scale is nuanced and often subjective, but ultimately important to keep your writing clear and concise.

A scope is the subject matter that your documentation will cover. Like with setting a baseline, you should set a scope for your page before you even begin writing it. Define a few bullet points that describe at a high level what your page will be about. Place them under the baseline section on your page, with a header named "Scope".

Here is an example scope I might set for the Redux page I mentioned above.

# Starting out with Redux

## Baseline

...

## Scope

- What problem does Redux solve?
- Application Structure
- The Store
- State, Actions, Reducers

Like defining a baseline, this accomplishes a few things for you.

It helps you divide on a micro scale. The act of outlining your desired scope for a page forces you to consider what content you include on the page. If you notice you have many topics listed under your scope, consider trying to break them up into a few categories and divide that content across multiple pages. Too many items within a scope can lead to long-drawn-out documents. Oftentimes, readers will have an easier time digesting information if it is broken up into clear discrete parts.

It keeps your writing on track. Now that you have a set of bullet points that outline what the page will cover, you have a defined starting point to start writing from. Pick a bullet point and start writing. Again, if you notice a particular topic starts to drag on, consider splitting it out into its own page with a baseline and scope of its own. The scope also defines a clear end state for the page - once documentation has been written for each item in the list of scope, then you know you are done. A well-defined scope keeps your documentation concise.

It signals to the reader what the page will cover. If the reader reads the scope and determines that this page does not cover what they need to learn, they can leave immediately and not waste any of their time reading the page. If the scope does cover what they would like to learn, now they know exactly what to expect from this page. Setting expectations upfront with the reader gives them a clear idea of what they are getting themselves into when sitting down to read your documentation.

The Takeaway

Defining a baseline and a scope are two easy and time-efficient ways to instantly improve your documentation. It aids tremendously in the writing process while giving the reader valuable information at the same time. Perhaps you already internally think through these two aspects before writing a page. Putting your thoughts down on paper like this brings that planning to another level - you are already thinking it, so why not put write it down?

This physical contract keeps the writer true to their original plan. It acts as a set of guiding principles that keep you the writer on topic. When a baseline is defined, there is no need to explain details of Topic A to the reader - they already know about it. When a scope is defined, there is no need to write any more or less than what is dictated by the scope. These two simple lists go a long way towards making your documentation more clear and concise.

If you've enjoyed this content, consider subscribing to my mailing list to be notified whenever I release new content.

You should learn Markdown

Erik Melone — Fri, 03 Sep 2021 15:50:50 +0000

To improve your documentation writing, having a tool that reduces friction from getting a thought in your head into a nicely formatted document is important. Markdown is exactly the tool for this job.

What is Markdown

Markdown is an open-sourced markup language that you can use to easily create an aesthetically pleasing document out of a simple text file. A markup language lets you write symbols and special characters within a body of text to signify certain formatting in the document. For example, each markup language has a specific syntax to mark text to be bold, italicized, or even to be marked as a header. It takes all of the fuss out of formatting a document like you might have to in Microsoft Word.

Markdown is the simplest of markup languages, and therefore the easiest to learn. If you are familiar with other markup languages such as HTML or LaTeX, then learning Markdown will be a breeze for you as its syntax is by far the simplest. This is because where HTML is meant for rendering webpages and LaTeX is meant for writing mathematical papers, Markdown is simply meant to write documents easily.

The Simplicity of Markdown

At its core, Markdown has nine or so basic rules that you can use to accomplish 95% of all document formatting you'll ever want. Here is a comprehensive Markdown guide for basic syntax that you can read through. This guide is very extensive and may take a while to get through, so I have also provided an example of these nine rules working together to format a document.

Markdown is so appealing is because it removes all of the difficulty of formatting a document and encodes them into a very easy-to-understand syntax. It also strips away unnecessary formatting choices from the writer. My biggest pet peeve when I create a new document on Google Drive is having to make sure the font and font size are to my liking or having to deal with setting my margins properly. Markdown is all about what matters the most - the text you are writing. Problems like these are not apparent in Markdown because it simply removes that option altogether.

Another benefit is Markdown is that its file format .md is a universal file format that can be edited in any text editor, and opened in any markdown viewer. A big issue with Microsoft Word is that its .docx file type limits where you can edit the file. If you don't have a specific program installed on your computer to edit a .docx, then you'll have to turn to an online editor like Google Docs or Microsoft Word online. With Markdown, you can edit the file in any text editor. It is truly portable, and the same file can be used in many different applications without any conversion.

The stripped-down formatting options combined with the portability of the .md file is what makes the format useful yet simple. When you want to sit down and write some technical documentation or some notes, you don't want to worry about how to format it or compatibility issues across different applications. You just want to write, and that is exactly what Markdown enables.

Extended Markdown Syntax

It is also worth noting that there is more to Markdown than what you learned in the basic syntax. Markdown also has an extended syntax that builds upon the existing Markdown syntax. Unlike the basic syntax, the extended syntax is not supported by all Markdown editors and viewers. Most tools will state which features they support, so be on the lookout for that if you intend to use any of the extended features.

For a developer, one of the most useful extended syntax features is the ability to insert a fenced code block easily into a document. This is yet another reason why Markdown is appealing for a developer looking to write documentation. You can move between writing plaintext explanations to inserting code examples without any fuss.

Where to use Markdown

Markdown can be used in a variety of different places. Markdown Guide has a pretty thorough list of tools that support Markdown, though I am sure there are plenty more applications out there that support Markdown that did not make this list.

Slack is the place I find myself using Markdown the most often. Slack is far from a comprehensive Markdown editor, but it does support inline code highlighting and fenced code blocks. These two features are very valuable when it comes to communicating with colleagues. It is infinitely easier to understand a message about a technical problem when the code in the message is formatted differently than the regular text.

Without Markdown:

With Markdown:

Another place you'll see Markdown being used is on GitHub. By default, GitHub will render the README.md file in a folder when you are viewing that folder in the repository. Therefore, to write effective documentation for a repository you host on GitHub, knowing Markdown is a must.

There are also a variety of tools out there that let you write Markdown and render them on the web. Dev.to itself has you write your blog posts in Markdown - I am currently writing this post itself in Markdown! Prepare for inception:

GitHub Pages is another great tool that lets you turn a directory of Markdown pages into a full-blown website. On my old team at work, I led an initiative to create a set of Github Pages as a centralized source of documentation for the entire organization. This was a very simple, yet effective way to put all of our documentation and resources in one place. Be on the lookout for a future blog post on the creation of that.

I use Markdown daily in a variety of places. It is one of those underrated skills to know that people don't often mention but certainly improves both how we can write documentation writing and how we can communicate with peers.

If you've enjoyed this content, consider subscribing to my mailing list to be notified whenever I release new content.

The Importance of Writing Documentation in the Workplace

Erik Melone — Sat, 28 Aug 2021 11:50:54 +0000

Tribal Knowledge

One of the most important realizations I have made in my early years of working as a Software Engineer is how big of a role that "tribal knowledge" plays within an organization. I use the term "tribal knowledge" to mean important information that is passed from person to person through impromptu meetings or instant messaging. This information can range from complex implementation details of a microservice to even just invoking that microservice's endpoints. It took me a solid 3 months on the job to even learn how to hit the happy path of the ecosystem I worked on. How did I learn? Someone shared me a private Postman Collection they had stored away on their computer, hidden from any new engineer that joins.

As time went on, I interacted with more and more engineers who were way more experienced than me. I learned who explained concepts in the most easy to understand way, and made the extra effort to absorb as much information from them as possible. I also learned who didn't explain concepts super well, and never really went back to them with more questions when I realized that I never got the answer I needed. And that's the issue with tribal knowledge - you only can learn as much as those around you are able to teach you. And this can be extremely limiting.

Once I reached a more tenured status within the organization, I started interacting with more individuals across the team boundaries. After various interactions with a particular team, I began to realize that the junior engineers barely knew their own systems, and the senior engineers were terrible at explaining the systems. This isn't to say that these senior engineers had no clue about their own systems, they very clearly did. The issue is that they could not effectively communicate their knowledge to anyone else. Therefore, all of the information they have accumulated, and all of the information passed to them from previous engineers will never be effectively passed on to the next "generation" of engineers.

The downfall of an organization

The problem with this word of mouth approach of information sharing is that if at some point the chain of communication breaks, all of the information passed down through the "generations" of engineers before will ultimately be lost. It could be an incredibly smart person who cannot explain concepts to a newcomer, or someone who has a hard time understanding the system no matter who explains it to them. In either case, the moment information stops flowing is the moment a team or organization can get into trouble.

The point where this becomes a major problem is when the number of these communication breaks reaches a critical mass. Suddenly, it feels like the general population of engineers simply does not know as much as it used to. Basic employee turnover has experienced engineers moving on and new engineers coming in. But because there are more broken links in the delicate chain of tribal knowledge, there are less people who can effectively train and teach the new engineers. Repeat this a few times, and the effect compounds. Suddenly you have a organization flushed with plenty of new faces who never got the proper training they needed to thrive. This is how an organization dies.

This is not something to be pinned on individuals, but rather on the greater system. You could be the smartest engineer alive, but if you are new to the team and have no one who can teach you all the organization specific secrets, how will you ever learn the organization's ecosystem? This system of passing tribal knowledge from person to person is easy to execute and flexible. When you have the right pairings of people, it works really well. But ultimately it is fragile, and is able to destroy an organization frighteningly fast. Rather than completely replacing the system, supplementing it with clear concise documentation that permanently records important information about an organization can help keep it from collapsing.

Invest in Documentation

The main reason an organization falls victim to the poison that is tribal knowledge is the notion that documentation takes too long to write - it takes time away from developing features that contribute to business value. Therefore, writing documentation gets deprioritized and ultimately rarely ends up happening. The truth is that writing documentation does not need to be difficult or involved. Even a couple of hastily thrown together paragraphs that explains a piece of business logic in code can be shockingly helpful. Rather than requiring a word of mouth knowledge transfer, it is now out there in the open for anyone to read. If someone reads this documentation and still needs further clarification, then scheduling a knowledge transfer can be helpful. Bonus points if the engineers update the documentation after their KT session.

If that is not convincing enough, consider the practice of writing Unit Tests. We could use the same excuses against writing Unit Tests as we do against writing documentation: they take too long to write and don't directly contribute business value. But, we still write tests because we know it will help us in the long run. Automatically testing our code helps ensure that we maintain a clean, bug free codebase. In the same vein, writing documentation helps us in the long run as well - it ensures that our transfer of knowledge is clear and consistent.

If your team already includes Unit Testing as part of its feature development process, then implementing the practice of writing documentation is easy. Just as you make sure to include Unit Tests before you submit code for review, make it a point to also write documentation before you submit your code for review as well. Better yet, make sure to submit documentation for review in addition to submitting code and Unit Tests. This way, not only are you writing documentation as you create a new feature, but the team also plays a part in contributing to that documentation as well.

The Takeaway

Documentation is key to the maintaining a healthy transfer of knowledge within an organization. By taking thoughts in our heads and putting them in writing, knowledge transfers are no longer a temporary event - they become a permanent fixture in the organizations ecosystem. An engineer that joins years after another quits can still get a glimpse into the thought process of that ex-engineer. It becomes infinitely more valuable and sustainable than word-of-mouth sharing of tribal knowledge.

If you've enjoyed this content, consider subscribing to my mailing list to be notified whenever I release new content.