The Plain Text That Runs The Web: Why Developers Write Documentation In Markdown
A README is the first thing you'll see when you open nearly any well-known open-source repository on GitHub. Not a Word document, not a well-designed webpage, not a polished PDF. Just neat, organized text written in Markdown. Developers hardly notice it anymore because it has become so commonplace. Since this quiet ubiquity wasn't an accident, it is worth investigating.
John Gruber and Aaron Swartz developed Markdown in 2004 with the seemingly straightforward objective of enabling authors to format plain text so that it could be easily converted into HTML without requiring them to think in HTML. The appeal took off right away, especially for developers.
People were already accustomed to using text editors, version control systems, and terminal windows, and all of a sudden there was a way to create structured documentation that worked well in all of those settings. No specialized software. Not a proprietary format. The code is directly adjacent to a `.md` file.
There's a feeling that Markdown's solution wasn't actually a formatting issue. It resolved a friction issue. There was a real awkward gap for developers writing documentation prior to the widespread use of Markdown. Rich text editors created files that were difficult to diff or version cleanly.
Writing prose in HTML tags is nobody's idea of flow, raw HTML did work. Like it had been measured for it, Markdown slid into that opening. Writing, committing, reviewing publishing could all be done without ever leaving the workflow used for the rest of the development process.
Probably the most overlooked component of that puzzle is version control. Documentation stored in Markdown files within a Git repository has access to the same infrastructure for branching review and change tracking as the code itself. Pull requests for code changes and pull requests for documentation changes are identical.
In practice, this alignment is important because it makes it easier to update documents when changes occur within the codebase. Separate documentation from the code has a tendency to stray. Adjacent Markdown files have a good chance of remaining accurate.
It's also important to note how many developer platforms have subtly made Markdown the default authoring layer. Hashnode, Dev.to, GitHub GitLab. Notion. Discord. Stack Overflow. Jupyter Notebooks. Slack, to a certain extent. Every platform independently reached the same conclusion.
Markdown is sufficiently similar to natural writing for non-technical people to understand sufficiently close to code for technical people to accept. That is a significant design accomplishment. The majority of formatting schemes ultimately benefit one audience at the expense of another.
The loyalty is explained by the syntax itself. headings using hashes. For emphasis, use asterisks. Code backticks. lists with dashes. These decisions were based on the customs that developers had been using informally for years in plain-text email culture. Learning Markdown is more like realizing that what you were already doing had a name than it is like learning a new language. Even without formal training, the majority of developers are able to read a Markdown file.
Some people are still taken aback by how far the format can go when necessary. Tables, task lists, syntax-highlighted code blocks collapsible sections are all included in GitHub Flavored Markdown. For situations where native syntax is insufficient such as a resizable image, a custom button, or a responsive video embed the majority of Markdown parsers support embedded HTML. Despite the increasing complexity of documentation requirements, Markdown has remained relevant due to its hybrid capability. It is adaptable without requiring you to consider it every single day.
It's probably safe to say that Markdown isn't the ideal format. Remixed reliably classified Markdown does start to show its limitations for large documentation projects with deep structural requirements content that must be reused. Structured content requires more than just headings and bullet points to be meaningful in a variety of contexts, which is why formats like DITA and DocBook were created.
Those systems were never widely adopted, the issue they were trying to solve was genuine. Markdown covers the ground sufficiently that the tradeoffs hardly matter for the great majority of what developers actually need on a daily basis, including README files, API documentation, changelogs, technical blog posts, inline code comments project wikis.
And that's arguably the most straightforward explanation for why developers use Markdown for documentation. Not because it's the most comprehensive format in theory. since it fits. It fits the environments where developers already spend their time, as well as the tools, workflow mindset. Many passing visitors have become active contributors thanks to a well-organized README in Markdown. It is difficult to dispute that result.
