The Ultimate Tool for Writing Great Documentation on GitHub
4 min read
Are you tired of messy and inconsistent documentation? Look no further than Markdown! In this blog post, we'll explore the ins and outs of this popular markup language and show you how to use it to write great documentation on GitHub.
What is Markdown?
Markdown is a simple and easy-to-use language that allows you to write structured, clear and consistent documentation. It is widely used by developers, project managers, and technical writers as a markup language to write content on GitHub.
How to use Markdown
Headers are a great way to organize your content and make it easy to scan. To create a header in Markdown, simply add a
# symbol at the beginning of a line, followed by a space and your text. The number of
# symbols used will determine the size of the header. For example:
# H1 ## H2 ### H3 #### H4 ##### H5 ###### H6
Lists are another great way to organize and present your content. You can create bullet points or numbered lists by simply adding dashes (
-), asterisks (
*), or plus signs (
+) in front of line items. Indent one or more items to create a nested list. For example:
- item 1 - item 2 - item 3
1. item 1 2. item 2 3. item 3
To add images to your documentation, use the following format:
![alt text](image url)
Make sure to use the proper URL of the image you want to include.
You can add links to your documentation using the following format:
Tables are an excellent way to present information in a structured format. To add a table, use three or more hyphens (
---) to create each column’s header, and use pipes (
|) to separate each column. For compatibility, you should also add a pipe on either end of the row. For example:
| Column 1 | Column 2 | Column 3 | |----------|----------|----------| | Row 1 | Row 1 | Row 1 | | Row 2 | Row 2 | Row 2 |
Emojis are a fun and easy way to add personality and emotion to your documentation. You can include emojis in your markdown by typing in their corresponding colon notation. For example, to include the 🔥 emoji, you would type
:fire:. A comprehensive list of emojis and their corresponding colon notation can be found on websites such as Emoji cheat sheet.
Table of Contents
A table of contents (TOC) is a helpful way to organize and navigate long documentation. You can generate a TOC in markdown by using special syntax or by using a TOC generator tool. For example, in GitHub, you can include a TOC by adding
* [section](#section) for each section you want to include in the TOC.
Code snippets are an essential part of any technical documentation. To include code snippets in markdown, you can use code fences. Code fences are used to create a block of code, You can create a code fence by using the
``` symbol at the beginning and end of your code snippet, followed by the programming language you are using.
Blockquotes are a great way to set apart and emphasize a specific quote or passage of text. To create a blockquote in markdown, simply add a
> symbol at the beginning of the quoted text. For example:
> Knowledge speaks, but wisdom listens.
Tasklists are a helpful way to create a checklist or to-do list in markdown. To create a tasklist, add
- [ ] or
- [x] before each task, for example:
- [x] Take a look at the markdown guide - [ ] Write a blog post on markdown - [ ] Publish the blog post
By mastering Markdown and all the related tools, you can write clear and consistent documentation that is easy to read, easy to understand and easy to use. With this knowledge, you can create documentation that is simple, efficient, and user-friendly, this will help you a lot to communicate with your team and to create better projects.
Don't forget to share your thoughts and feedback in the comments section below. And remember, practice makes perfect!
Sign up for Training
Want to learn more about Markdown and other DevOps tools? Sign up for my newsletter by visiting mrbilalshafiq.com/newsletter, follow me on Twitter here, and book your seat for the AWS training day on Saturday, 14th January 2023 between 1pm-6pm GMT by sponsoring any amount to reserve your place.
Did you find this article valuable?
Support Bilal Shafiq by becoming a sponsor. Any amount is appreciated!