Sometimes it can be a challenge to decide the best format to keep technical and project information documented. In this blog post we discuss some of the advantages of using markdown files and format to store your technical documentation.

Why Markdown

Documentation is an integral part of any technical project, and it’s essential to have a consistent, clear, and concise way of documenting the project. Markdown is a lightweight markup language that provides an easy and efficient way to create technical documentation. In this blog post, we’ll explore the advantages of using markdown for technical documentation.

1. Markdown is easy to learn and use One of the significant advantages of using markdown for technical documentation is its simplicity. Markdown is a lightweight markup language that uses plain text formatting to create rich text documents. With markdown, you don’t need to be an expert in HTML or other markup languages to create well-formatted documentation. Anyone with basic knowledge of plain text formatting can start using markdown right away.
2. Markdown is platform-independent Another advantage of markdown is its platform independence. Markdown documents can be created and viewed on any platform, whether it’s a desktop, mobile, or web-based device. This makes it easy to share and collaborate on documentation across different teams and devices.
3. Markdown is versatile Markdown provides a variety of formatting options that can be used to create different types of technical documentation. You can use markdown to create documentation for software projects, API documentation, system documentation, and much more. Markdown also allows you to create tables, lists, code blocks, and other useful formatting options.
4. Markdown is version control-friendly When it comes to managing technical documentation, version control is crucial. Markdown documents can be easily version controlled using Git or other version control systems. This allows teams to collaborate on documentation, track changes, and roll back to previous versions if needed.
5. Markdown is SEO-friendly Markdown is a great tool for creating SEO-friendly technical documentation. With markdown, you can easily add meta descriptions, keywords, and other SEO elements to your documentation, making it more discoverable and accessible to search engines.
6. Markdown is extensible Markdown is also extensible, which means you can add custom tags and extensions to enhance the functionality of your documentation. This can include things like math notation, footnotes, or other custom elements that are specific to your project.

In conclusion, markdown is a powerful and versatile tool for creating technical documentation. Its simplicity, platform independence, versatility, version control-friendliness, SEO-friendliness, and extensibility make it an excellent choice for documenting technical projects of any kind. Whether you’re working on software, hardware, or any other technical project, using markdown can help you create clear and concise documentation that is easy to share, collaborate on, and maintain over time.

Can we make it better with automation?

We can take advantage of the shells that are built into modern operating systems to help automate the process of markdown documentation including PowerShell and bash/zsh.

We have recently been developing several scripts to help automate the documentation of servers and services. If you are interested in trying them out, we have made them available via GitHub.

To get started, clone the repository, open the shell of choice (please note most of the scripts have been written for PowerShell) and run your required script to output the plain text data to the console. Alternatively, you could pipe the output to a file and transfer it directly into your documentation repository. For example, the following command would save the ServerDocumentation.ps1 script to a file called “ServerDocumentation.md”

C:\ PS>./ServerDocument.ps1 > ServerDocumentation.md