DEV: Markdown and Documentation

It is essential to provide documentation in your code repositories so that others know what the code does and how to use it. By understanding the power of Markdown for creating files such as README, CHANGELOG, and TODO you can ensure your code (and hard work) is helpful to others.

10 Things to Get Started with Markdown:

1. What is Markdown?

• Markdown is a way to format text using simple symbols, so it looks good on GitHub, documentation, or websites. It’s easy to read even in its raw form, and files usually end with .md or .markdown.
• Markdown is a type of markup language (like HTML, but much simpler).

2. Basic Headings and Text:

• Use # for big titles, ## for subtitles, and ### for smaller headings.

  # Main Title (H1)
  ## Section Title (H2)
  ### Subsection (H3)

• Italic: *italic* or _italic_
• Bold: **bold** or __bold__
• You can combine them: **_bold and italic_**

3. Lists:

• Unordered (bulleted) lists:

  - Item 1
  - Item 2

• Ordered (numbered) lists:

  1. First
  2. Second

• You can nest lists by indenting with 4 spaces / pressing tab once

4. Links and Images:

• Add a click-able link:

  [Google](https://www.google.com)

• Show an image:

  ![Alt text](image.png)

5. Blockquotes and Code

• Blockquote (for quotes or notes):

   This is a quote or note.

• Inline code (for short code):

  Here is some `inline code` in a sentence.

• Code block (for longer code):

  ```js
  console.log('Hello, world!');
  ```
  

6. Tables:

• Organize data in a table:

  | Syntax    | Description |
  |-----------|-------------|
  | Header    | Title       |
  | Paragraph | Text        |

• You can align columns with colons (:)

  | Name        | Age | City           |
  |:------------|:---:|---------------:|
  | Alice       |  25 | New York       |
  | Bob         |  30 | San Francisco  |
  | Charlie     |  22 | London         |
  
  :--- is left-aligned
  :---: is center-aligned
  ---: is right-aligned

7. Task Lists:

• Make checklists (great for to-dos):

  - [x] Task done
  - [ ] Task not done

8. Strikethrough, Highlight, Sub/Superscript:

• Strikethrough: ~~text~~ (shows as text)
• Highlight: ==text== (shows as ==text==)
• Subscript: H~2~O (shows as H₂O)
• Superscript: X^2^ (shows as X²)

9. Collapsible Sections, Diagrams

• Collapsible (click-to-expand) sections:

  <details>
  <summary>Click to expand</summary>
  Hidden content goes here
  </details>

• Diagrams (ASCII art or text):

  +-----+
  | Box |
  +-----+

• You can also draw simple branch diagrams for Git:

  main
   |
  dev
   |\
  test beta

10. GitHub Flavored Markdown: Markdown, but supercharged:

• It is a "dialect" of Markdown that is supported for user documentation on GitHub
• contains features like diagrams, mathematical expressions, relative paths / linking to files inside the same repository, tasks lists converted into GitHub Issues, extended formatting for tables, auto-linking to GitHub Issues, Pull-Requests, and repositories, as well as rendering code snippets from other codebases via linking
• For more information about the GitHub Flavored Markdown, visit In-Depth Guide about features of GitHub Flavored Markdown

How You Can Use Markdown for Documentation:

• Markdown is an amazing tool for documenting projects and codebases. Since Markdown does not require you to use HTML tags in order to format your content, you can produce well-polished documentation quickly
• for example, creating a heading in HTML would look like: <h2>This is my wonderful heading</h2>, whereas in Markdown, all you need to do is type ## This is my wonderful heading
• As a result, many organizations working on software projects use Markdown + Markdown Documentation Best Practices in order to write their documentation.

Common Documentation Files and their Best Practices:

1. README.md

• This is the first piece of documentation that people see when they land on your codebase's GitHub or CodeCommit repository
• This README.md should provide a clear and high-level overview of all the essential information required for a user to get started with your code
• These are a list of best practices that you should follow for your README.md files:
  1. Start with a clear title, and a brief description of what the project does
  2. Include a table of contents for longer README files to help with navigation
  3. Provide clear installation instructions, with code blocks using the ``` codeblocks ``` in markdown to show commands
  4. Explain how to use the project with simple examples
  5. If possible, include screenshots of the working product to act as a reference for people looking to get a general overview of the project
  6. Include contact information, as well as links to any additional resources / links
• For a comprehensive guide about writing effective README.md files, visit GitHub's official guide on writing a great README

2. CHANGELOG.md

• The CHANGELOG.md file serves as a chronological record of all notable changes made to a project, such as new features, bug fixes, or improvements.
• Keeping a changelog helps users and contributors understand how your project has evolved over time
• These are a list of best practices that you should follow for your CHANGELOG.md files:
  1. List all changes in reverse chronological order, with the most recent changes appearing at the top
  2. Use clear headings for each new version, for example: ## [1.2.0] - 2025-08-21
  3. Group changes under specific categories like Added, Changed, Fixed, Removed, or Security, to make the log easier to read
  4. Keep the descriptions concise and focused on what was changed, avoiding internal or unnecessary details
• For a comprehensive guide about writing effective changelog files, visit Keep a Changelog's guide on best practices

3. TODO.md

• The TODO.md is a simple, plain-text checklist for tracking tasks, bugs, or future ideas for a project
• This file is handy for quickly outlining work that needs to be done, whether for an individual developer or a small team
• These are a list of best practices that you should follow for your TODO.md files:
  1. Use a task list format with checkboxes to easily track completion:
     • - [x] Task done
     • - [ ] Task not done
  2. Organize tasks with headings to group them by priority, feature, or release (e.g., ## High Priority, ## Next Release)
  3. Keep the list concise and to the point; it should be a working document, not a detailed project plan
  4. Include short notes or links to relevant issues to avoid cluttering the list with long descriptions