Why do I have these README.md files? What’s a .md file?
The .md file extension stands for “markdown”
You likely see them in your new git repositories. You folks migrating from the mainframe might see them and wonder what they are, and why it has funny characters. You’re used to having Word documents scattered everywhere: shared drives, Sharepoint, Wiki’s and more. Those documents are often hard to track down, and worse: they are stale. Markdown is designed otherwise be version controlled and to be stored with your source code.
What Markdown Is
Markdown is a lightweight, plain-text markup language for formatting documents using simple, readable syntax (e.g., #for headings, **bold**, - for bullet lists) instead of complex formatting codes. Files typically use the .md extension. It was designed to be readable as plain text even before it’s rendered into HTML or another output format.
Why Markdown Files Are Important
1. Portability & Longevity
Markdown files are just plain text — no proprietary format, no vendor lock-in. A .md file written in 2010 opens identically today in any text editor, unlike a .docx that may hit compatibility snags across Word versions.
2. Version Control Friendly
Because it’s plain text, Markdown works cleanly with Git and other version control systems — diffs are readable, merges are manageable, and history is meaningful. This is a big reason it dominates in software/technical documentation (READMEs, wikis, changelogs).
3. Toolchain Flexibility
A single Markdown file can be converted to HTML, PDF, Word, slides, or static websites (via tools like Pandoc, Jekyll, Hugo). Write once, publish anywhere.
4. Low Friction, High Readability
The syntax is minimal enough that people write and read it naturally, but structured enough to convert reliably into polished output — a good middle ground between raw text and heavyweight formats like Word or LaTeX.
5. Ubiquity in Technical & Developer Ecosystems
GitHub, GitLab, Jira, Confluence, Slack, and most developer tools render Markdown natively. It’s become the default language for documentation, blog drafts, and knowledge bases in technical organizations — including static-site blog platforms often used for content like your Strongback posts.
6. Future-Proofing Institutional Knowledge
Because it’s non-proprietary and human-readable even unrendered, Markdown is a solid choice for documentation meant to outlast any specific software — useful for things like architecture references or “owner’s manual”-style documentation.
So, next time you need to document how a git repository is laid out, use a README.md. You could even use a ABC123.md to document a Cobol member named ABC123.cbl. To learn the syntax of markdown, check out https://www.markdownguide.org/basic-syntax/
