✍️ Markdown for Technical Writing

When you're starting in technical writing for software, you might wonder what skills you all need. Do you need to learn a programming language, handle Git, or know HTML? In this post, we'll look at Markdown and if/where it might be helpful for technical writers.

Markdown - Yes or No?

I worked for 9 years as a technical writer at a large software company. As big companies have a complex setup and need a similar look and feel of their various products across many teams, they usually have pretty sophisticated documentation tools and workflows in place. Therefore, there was no need to know Markdown.

However, when I tried to contribute to open-source projects, I realized that knowing the basics of Markdown can be pretty helpful. It's likely that smaller projects that require API documentation want to provide their documentation in a README file. Knowing about Markdown can help you prove that you're up to the task.

So, is Markdown useful for technical writers?
Markdown is useless for technical writers

I'd disagree, as you can see at the strike-through. But then, where does it come in handy? Here are some aspects to consider.

When Markdown Can Be Useful for Technical Writers

In general, the most common use case is probably for technical writers of software documentation. In this field, there are various use cases where Markdown is helpful.

API Documentation
If you provide API documentation for smaller open-source projects, it's likely that the team uses a README.md file to provide the documentation. Being able to use Markdown comfortably is a requirement for those who are providing the documentation.

Blogging as a Technical Writer
Many technical writers started as plain writers, meaning writing blog posts. Not all blogs require Markdown, but especially in the software world, blogging in tools relevant to the industry - such as GitHub and Co. - can be done with Markdown.
Plus, providing your writing portfolio in GitHub can give you an extra edge when it's time to apply for a job as a technical writer in the software industry.

Working as a Freelance Technical Writer
When you're employed as a technical writer, the onboarding process usually entails training for the documentation tool used in that company. Your focus should then be to learn how to use this one tool by heart.
However, when you're a freelancer, you want to be flexible and open to many projects, irrespective of the tool or output format your client asks you to use. Especially smaller projects might have more basic tool requirements where Markdown can come in handy.

Pros and Cons of Markdown for Technical Writing

Here are some pros and cons of using Markdown as a technical writer, so you can make an informed decision whether it's worth learning it.

Pro Markdown

1. Platform Independence: Markdown files are plain text and work across all operating systems, so whoever you're going to send the file to will be able to read it.
2. Supported by Many Tools: Many tools from documentation tools to blogs and development tools use Markdown, so you're not stuck with one proprietary tool when using it. Especially as a technical writer for software products, you'll encounter it in GitHub, GitLab, and developer-focused platforms.
3. No Interruption While Typing: One of the biggest pros in my opinion is that you can focus on writing and keep typing along. No need to stop to select text and choose the right formatting. I think this really helps to keep up the creative flow.
4. Tool Support: Popular technical writing tools (for example, Visual Studio Code or Obsidian) support Markdown natively or with plugins.
5. Ease of Use: Markdown can be learned within 15 minutes, and the basic syntax is intuitive and easy to remember.

Con Markdown

1. Basic Formatting Only: The syntax is intentionally pretty basic and not built for complex formatting. However, you can add to the basics with HTML and CSS or additional tools.
2. Lack of Standardization: While you can write in Markdown in a simple text editor, previewing or rendering the output requires a corresponding tool. As Markdown doesn't have strict rules on how it can be interpreted, you might get different results depending on the rendering tool.
3. Translation: When your documentation requires translation, it can lead to missing or wrong Markdown syntax. Standard translation tools like Trados can usually handle Markdown files, but the translator should know the basics about Markdown to not accidentally delete or change the Markdown in the translation.

How to Learn Markdown

Now, all of the aforementioned sounds great and promising, but how do you go about learning Markdown? Let's dive into a structured plan for learning Markdown.

Suggested Plan to Upskill on Markdown

"I love it when a plan comes together." (John "Hannibal" Smith, the A-Team)

---

Here's how I'd go about learning Markdown:

1. Read online about Markdown. There are lots of great and clear overviews on the subject. For example, refer to this Markdown Guide. Be aware that some tools use a "flavor" of Markdown, such as GitHub. Refer to their specific GitHub-Flavored Markdown Guide.
2. Take a course about Markdown. Udemy, Coursera, and many other online learning platforms offer affordable courses. This will help you practice what you read about in step 1. YouTube also provides great videos about learning Markdown (for example, The Only Markdown Crash Course You Will Ever Need).
3. Showcase your Markdown skills. Use Markdown to create your portfolio, or reference a post you created using Markdown. This will showcase your skill to your current (or soon-to-be new) employer or client.

How much time should I set aside to study Markdown?

Actually, Markdown is so simple that it usually doesn't take long to understand. If you look up a list of the basic syntax, you can be done in 15 minutes. If you want to practice it a bit while learning the syntax, 1 hour will be sufficient.
Not too bad, right? I guess anybody has the time for such a short upskilling session.

Examples for Markdown

Here's an example of what Markdown syntax looks like while writing in a plain text editor:

### Suggested Plan to Upskill on Markdown


> "I love it when a plan comes together." (John "Hannibal" Smith, the A-Team)
___

Tools for Technical Writers that Use Markdown

Let's have a look at the various tools that support Markdown specifically.

Documentation Tools

• Docusaurus: This open-source documentation tool is mainly used for developer-focused documentation, API docs, and guides.
• Read the Docs: Automatic documentation deployment tool where developers can use the same tools and workflows they use anyway in development (like GitHub, GitLab, and others). Best for software developers and technical writers documenting codebases and APIs.
• MkDocs: Best for simple and lightweight software documentation for technical development teams. Pages are written in Markdown and configured with a single YAML configuration file.
• GitBook: Collaborative product and developer documentation tool. Uses a WYSIWYG Markdown editor.

Other Tools Using Markdown

• GitHub: Use in software development. GitHub-flavored Markdown is used in README files and for the GitHub Wiki. GitHub makes sense for small to medium-sized documentation projects or codebase documentation.
• Obsidian: A note-taking app
• Swagger Editor: If you want to get technical, you can edit the documentation-relevant description texts for an API's endpoint, methods, and so on in the OpenAPI Specification File in the Swagger Editor. To format the description texts in the source file, use Markdown to include links, highlight texts, or format code snippets. In the following image, you can see the Swagger Editor to the left with the description texts using Markdown, and the rendered text in the API UI to the right.

Conclusion

Markdown is an easy-to-learn lightweight formatting option for simple texts. As Markdown is prominently used in the development environment, being able to read it is especially useful for technical writers who work closely with software developers. Here, you can use it in the following scenarios:

• Writing developer-focused documentation, such as APIs, SDKs, and technical guides
• Your audience is developers or tech-savvy users who prefer clean, lightweight content.
• Collaborating with software teams using Git workflows.

If your work involves software documentation, tools like Docusaurus, MkDocs, and GitBook are among the best choices due to their Markdown-first approach, ease of integration, and developer-focused features.

What about you, have you used Markdown for writing technical documentation? Which tools do you use? Let me know in the comments.

About Me

I'm a technical writer for software products. I've been working in the software industry for over 13 years, of which I spent the first 4 as a translator before I switched to technical writing. I focused on admin guides, release notes, UI texts, publication, and training colleagues.