Best Practices for Creating Markdown Documentation for Your Apps

Various formatting languages exist to manage how text appears in software documentation. One of the most crucial is Markdown. It provides a simple syntax for generating headers, emphasized text, ordered/unordered lists and more. Today, Markdown is a standard tool for authoring technical content, such as the projects found on GitHub or other web-based locations.

Markdown is a lightweight markup language used to add formatting to plain text documents. Created in 2004 by John Gruber, its primary goal is to enable people to write using an easy-to-read, easy-to-write plain text format that can be optionally converted to structurally valid HTML (or XHTML).

Essentially, Markdown allows you to create formatted text (like headings, bold text, italics, lists, links and images) using a simple syntax that is unobtrusive and remains highly readable even in its raw, unrendered form.

Documentation can be an essential part of any development project. It provides critical information, including:

• Enables the transfer and preservation of knowledge about the application.
• Enables collaboration and troubleshooting.
• Ensures compliance and quality.
• Enables scalability and feature enhancements.

Markdown’s simplicity makes it an excellent option for documenting projects. Be aware that there are a few different Markdown flavors, each with specific strengths. It’s critical that your organization standardizes on one flavor.

Common Markdown variations include:

• Markdown (original): The original specification.
• CommonMark: Clarifies aspects of the original specification for greater consistency. It is typically the standard flavor.
• GitHub Flavored Markdown: Adds more Markdown features, including tables, task lists, strikethrough and other components. Use this if you’ll be posting to GitHub regularly.
• Markdown Extra: Adds new features, including footnotes. Frequently used with WordPress.

Be sure to explore the capabilities of each tool before choosing one for your team.

Best Practices

Integrating Markdown into your documentation projects requires more than just selecting a version specification. Build on that critical first step by establishing formatting standards that fit the needs of your organization, team or project. Defining a style guide that enables all authors to create consistent documentation offers the best chance for success.

Consider the following best practices for using Markdown in documentation:

Planning: Plan for success by defining what the documentation should (and should not) cover. Define responsibilities, storage locations and Markdown flavor.

• Define the aspects of the application that the documentation addresses.
• Define who is responsible for authoring and maintaining the documentation.
• Specify a storage location. Ideally, documentation resides alongside the application in repositories like GitHub.
• Specify the supported Markdown flavor all authors should use.

Structure and organization: Organize documentation with a clear and logical structure that leads readers through necessary steps while building on concepts.

• Use three or fewer headers to define sections.
• Include a README.md file to explain the documentation scope, structure and purpose.

Formatting: Define and use a consistent format for all documentation.

• Bulleted lists are easy to scan and improve readability.
• Use numbered steps for sequential tasks.
• Apply date and time standards.
• Use internal links to reference other parts of the document.

Figure 1: Markdown displayed on the left with preview on the right. Note the headers, links and lists.

Syntax: Carefully manage code and command examples to ensure clarity. Determine when to use inline code versus code blocks.

• Use inline code formats for individual commands, file names, flags or other code references.
• Use code blocks for substantial commands or snippets.
• Specify programming languages when using code blocks.

Figure 2: Use inline coding formatting for single commands. Use code blocks for larger snippets.

Clarity: Use simple language and avoid idioms. Remember that many documentation projects are translated into multiple languages.

• Spell out acronyms the first time you use them.
• Avoid slang terms.
• Add metadata at the top of documentation files to summarize content.
• Rely on short paragraphs and sentences to maintain simplicity.
• Carefully check documentation for spelling and grammatical errors.
• Don’t overuse italics, bold, underline and other methods of emphasizing information.

Accessibility: Plan for accessibility when writing documentation, especially around URLs and images.

• Use alt text for images to support screen readers. Alt text also helps with SEO.
• Provide descriptive text for URLs and images.

Figure 3: Descriptive alt text aids screen readers and SEO results.

Consistency: Consistent formatting, vocabulary and organization empower helpful documentation.

• Develop a style guide for all documentation authors to follow.
• Use Markdown linting tools to catch errors and maintain style.
• Request feedback from users on how to improve documentation.

Maintenance: Update documentation when the application versions up.

• Bake documentation resources (time, money, etc.) into the version update plan.
• Ensure new sections are consistent with the rest of the document.
• Create new internal links for new sections.

Continual improvement: Strive for continual improvement of documentation.

• Solicit and integrate user feedback.
• Ensure documentation organization remains logical across version changes and feature enhancements.
• Carefully review documentation to catch inconsistencies and errors.
• Test all internal and external links to avoid broken links that lead to confusion or frustration.

Many applications, especially open source projects, rely on an entire community to maintain documentation. Style guides, templates and clear expectations are critical in these collaborative environments. Recognizing that many people will work with the documentation over time is essential.

To Edit Is Divine

Finding the right editor is another essential part of using Markdown to document your projects. While any basic text editor will work, a tool capable of displaying a preview is very helpful. One that offers linting or syntax checking will also help.

Many common editors are extensible and can be made to work with Markdown. Be sure to check your existing tool set to see whether you already have a familiar Markdown utility.

• Visual Studio Code: Your coders may already be using this editor, making it easy to modify its configuration for Markdown.
• StackEdit: A web-based editor with integrated preview and editing windows. It includes integration with cloud storage such as Dropbox and Google Drive.
• Typora: Offers excellent preview capabilities and advanced features.
• ghostwriter: A feature-rich editor with focus mode, various export capabilities and live preview options.

Spend some time evaluating these applications before standardizing.

Wrap Up

More and more IT departments rely on code-based projects, from traditional development work to Infrastructure as Code. Ensuring your development and administration teams generate accurate, straightforward and current documentation is crucial to the long-term success of IT projects. Markdown is a great tool for satisfying this requirement.

You’ll choose Markdown for its simple yet robust formatting capabilities, making the job of documentation applications far less cumbersome. Follow the above best practices to provide the best chance of success.

Damon M. Garn owns Cogspinner Coaction, LLC, an IT writing and editing company. He authors articles, tutorials, and labs for today’s top IT industry leaders. He regularly contributes to The New Stack, TechTarget, and CompTIA. Damon has 20 years of...

Read more from Damon M. Garn