Markdown Best Practices

There’s a roiling sea of tools and formats to consider if you’re a writer, especially a tech writer.

Markdown

You may find a framework for any purpose, from DITA to Frame, LaTeX to SGML, Confluence to MediaWiki. Markdown is one that keeps popping up as a lightweight writing format, a lingua franca for other file formats, and an enticement to encourage developers to better document their code.

Markdown File Naming Conventions

• When using standard markdown use cases, as is standard, capital letters should be used (as in the following examples) CHANGELOG.md, README.md, CONTRIB.md, LICENSE, note LICENSE does not have a .md extension, it should be plain text. These can/should be placed in the root directory of your repo.
• To prevent cluttering the root name space in repos, any “non-standard” documentation should be placed in a docsfolder off the root.
• When using a “non-standard” name, camel case filenames should be used e.g. docs/myAdditionalDocumentation.md.

Code Highlighting

The code highlighting syntax uses and is colored with. It follows the same syntax as regular Markdown code blocks with ways to tell the highlighter what language to use for the code block.