Why Markdown?
Contributing to a project you’ve never worked on can be daunting and there can be an overwhelming amount of information to get started. Most people are at least familiar with a README file as an entry point into any good repository. We’re going to cover some best practices when writing Markdown (MD) and show 5 features that will help you avoid common pitfalls we’ve experienced. Whether you want to reduce maintenance strain or lower the barrier for new developers, there are several patterns to make for a better experience.
Often Overlooked Markdown Features
There are many out-of-the-box features included in Markdown; we’ve chosen to highlight a few that will help you front load the pertinent information you want someone to be able to gather quickly while still allowing for the deeper technical documentation to be included.
Note: Markdown implementations vary slightly from platform to platform. The information here has been validated on GitHub, but check the documentation for your markdown platform/renderer to see which features are available for you.
Checkboxes
Checkboxes can be a great tool, whether you’re creating a grocery list or trying to help organize tasks for your development team. Markdown syntax for a checkbox is super simple, and when used in the right context it can make a world of difference in tracking progress. This feature especially comes in handy when doing pull request templates, but there’s more to come on that later.
Collapsible Text
Collapsible text is useful when you have multiple sets of instructions that aren’t necessarily pertinent to all parties — i.e. you have instructions based on specific platforms. Being able to hide that type of information allows you to keep the most important general information in focus on the screen without overloading the reader with topics that may have no use to them.
Text Highlighting
Text highlighting can be particularly useful in a README if you want to bring attention to important information or a caveat that deviates from the expected outcome. It can also be useful in Pull Requests to make sure a requirement isn’t missed. While highlighting text is not a new concept, it’s often overlooked when writing documentation.
Pull Request Templates
Pull Request (PR) templates are prevalent across many of the top open-source projects. However, many teams overlook the importance of having a clearly defined set of requirements to get code merged for enterprise repos. PR templates fill this gap and they not only make it easier for new developers to get started but also act as tools to prevent additional technical debt from piling up in your projects. A great example of PR templates in action can be seen in the Angular project, which has over 2.5 million users and 25k+ commits. With that many commits and over 143 active pull requests (at time of writing), some level of standardization is crucial to ensure standards are met.
While this lends itself to open-source projects, you may find yourself asking “Is this relevant to my repositories and my team of 5 developers?”. Well, the short answer is “yes”. An immediate value could be giving a new developer a simple task and having them raise a PR into the default branch. The feature itself is not the focus, but rather to allow them to see your team's requirements for code to be merged. Getting hands-on experience with the PR process is the primary goal of the exercise. Documenting the steps you take when performing reviews is also beneficial in uplifting junior developers by showing what you’re looking for in these reviews and reducing the amount of time spent.
ReadMe Templates
Combining some of the features that are explained above, you should be able to ensure your README files are user-friendly, cleaner, and easier to maintain. Used properly, this should minimize questions and let the documentation be the main source of knowledge transfer for a given topic. Applying a templated approach to this across your organization will increase the velocity at which information is consumed and learned at both the producer and reader levels. Projects vary widely in both complexity and content, and having a standard approach will keep readers from becoming overloaded by even the largest projects and ensures a standard is set at the onset of a new project.
Final Thoughts
The benefit of using these markdown features and taking a templated approach should largely be self-explanatory. However, we hope this additional context enables you and your organization to make the leap into leveling up your current markdown usage, or provides a few additional tricks to use going forward. It's also a good idea to implement an extension or two in your local development to aid writing MD files. Microsoft's VS Code has a plethora of good extensions to use, with Markdown Preview Enhanced being one of the most popular. Having a wealth of tribal knowledge should never be a point of pride. Useful documentation is key to being able to get a good night's sleep and taking vacations uninterrupted.
