How do you document and share your System Administration Tools and workflows?

1 Why document?

Documentation is not only a way to record your work, but also a way to communicate it. By documenting your tools and workflows, you can improve your own efficiency and consistency by having a clear reference and guide for your tasks. It can also enhance team collaboration and knowledge transfer by enabling you to share insights, tips, and solutions with others. Moreover, documentation can increase your credibility and professionalism by demonstrating your skills, expertise, and results. Lastly, it can reduce errors and risks by avoiding ambiguity, confusion, and misunderstandings.

2 What to document?

Documentation is essential for system administration work, as it covers the purpose, scope, and goals of your tools and workflows; the requirements, dependencies, and assumptions; the steps, commands, and parameters; the results, outputs, and feedback; and the maintenance, updates, and improvements. It is important to understand what they are for, what do they do, what do they achieve, what are the prerequisites and limitations for using them, how to use them with inputs and outputs, what are the expected outcomes and indicators, how to keep them up to date and secure, as well as how to optimize and enhance them.

3 How to document?

Documentation can take different forms and formats, depending on your preferences, needs, and audience. For example, you can use plain text files, such as READMEs, to provide basic information and instructions for your tools and workflows. Additionally, code comments like # or // can explain the logic and functionality of your scripts, programs, or configuration files. Diagrams, like flowcharts or network maps, can also illustrate the flow and structure of your tools and workflows. Screenshots like PNG or JPEG images can capture the visual output and feedback of your tools and workflows. And videos like MP4 or GIF files can demonstrate the usage and results of your tools and workflows. Lastly, there are various tools available to help with creating, editing, annotating, and recording documentation.

4 Where to document?

Documentation can be stored and accessed in different locations and platforms, depending on your preferences, needs, and audience. For example, you can store your documentation files locally on your computer or device, and use tools such as Git or Dropbox to sync and backup these files. Alternatively, you can store your documentation files remotely on your servers, using tools such as Apache or Nginx to serve and secure them. Additionally, there are online repositories such as GitHub or Bitbucket which can be used to host and manage documentation files. Wikis like MediaWiki or Confluence can also be used for this purpose. Finally, tools like Read the Docs or MkDocs can be used to host and manage online guides.

5 How to share?

Documentation can be distributed and shared in a variety of ways, tailored to your preferences, needs, and audience. For example, you can send files or links via email using tools such as Mailchimp or Sendgrid. You can also send files or links via chat using tools such as Slack or Discord. Additionally, you can publish your documentation on webpages or blogs with tools like WordPress or Hugo. Additionally, you can post your documentation on social media accounts or groups with tools such as Facebook or Twitter. Lastly, you can present your documentation on slides or videos with tools such as PowerPoint or Zoom.

6 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?