All About DEVELOPMENT.md

DEVELOPMENT.md as a technical document has existed for awhile. People generally come across them in Github repos from time to time. I don’t know how widespread it is, but I created my first DEVELOPMENT.md for EBWiki in 2015 after seeing many in the wild.

In general, I’ve been working on ways to have documentation be closer to the code. Years of handling projects with separate documentation sources taught me that sometimes it’s better to keep this documentation in the repository with the source code, but this doc would not be out of place in any team’s Confluence or Notion docs if that placement works for that team.

The first thing I put in there was a “Definition of Done” for tickets based on team discussions. Over time, we included documentation for setting EBWiki up locally, a list of third party sources and how to interact with them, and a General Timeline for contributing to EBWiki.

DEVELOPMENT.md Works; But Wait; There’s More!

One thing I’ve been working on this year is putting more thought and deliberation into how I use my tools. While the DEVELOPMENT.md has been a useful artifact, my current thinking believes it would be helpful to add a bit of structure to see what fits there better. Some examples of Tables of Content headers include:

Development Team Agreement Decisions

The first item from EBWiki was a team agreement decision. Decisions on configuring github repositories, coding styles, particular libraries or software packages chosen, software testing strategies, notes using REST clients and caching are just some of the examples of good DEVELOPMENT.md content. Another way to think of it is the doc that holds the most significant decisions from the team’s development Slack/Discord/Insert Asynchronous Collaboration App Here.

Developer Cookbook Recipes/HOWTOs

A Cookbook is a technical document where ways to solve problems are called recipes. These are step by step instructions to complete a task or process associated with a project. A helpful HOWTO can include code blocks to copy, or an animated image going through the sequence of instructions. HOWTOs are another name for docs like these. One benefit of outlining these is that if there’s code which is manual or ultra bespoke, it can be listed here and noted as an area of tech debt improvement.

Lightweight Architectural Decision Records

A way to describe the decisions made and why. While a “Lightweight ADR” may sound like an oxymoron to some, these are meant to be simple documents. There are five sections:

• Title - Self Explanatory. Some might add a number to count decisions
• Status - One of a set of enumerated values. proposed, accepted, rejected, deprecated, superseded
• Context - What are the reasons for this change? What pertinent history exists?
• Arguments - Is there are two or more paths to this solution, what are the arguments for either path
• Consequences - What occurred as a result of this decision, or how it was implemented

Teams can use a variety of ADR formats as they see fit. One recent example from a gig; I made docs with titles like “Using UUIDs to reduce sequential ID vulnerabilities”, “Using JWT for authentication”, and “Creating Pretty URIs”. The first ADR, which is the decision to use ADR is pictured below:

Example lightweight architecture decision record (LADR).

First Draft of DEVELOPMENT.md template

I’ve made a first draft of the DEVELOPMENT.md template in a README.md in a GitHub repository. I’ll be developing some material with that over time. If there is anything that resonates, please comment below, or find me on the internet!