I've created a niche automation tool that works perfectly on my system, but when I tried installing it on a coworker's machine, I realized it was much more complicated than I expected. Now, I want to thoroughly document the installation steps and explain the important variables involved. I'm looking for a good tool that allows me to document key parts of the code while including version control, as the tool is continuously evolving. Any recommendations?
5 Answers
Using Git along with Markdown is a solid choice! You can document everything in Markdown files. Just make sure to commit updates whenever you change your code. It's efficient and keeps everything in sync.
We switched to Vitepress recently for documentation, and it seems promising for our needs. Might be worth checking out if you’re looking for something specific and modern!
I recommend keeping high-level information in Markdown files within a 'docs' folder linked from your README.md. For more details, use inline documentation within your code with tools like Javadoc or Doxygen. This keeps your documentation relevant and easy to update because it’s right where the changes happen.
You should definitely use the same version control system for your documentation as you do for your code. Systems like GitHub let you create a Wiki or they natively support Markdown and other formats for documentation. This way, your documentation stays with your code changes.
You could document your code directly with docstrings and then generate your documentation in various formats like HTML or PDF. Most programming languages have tools to help with this, and it keeps your code and docs aligned!
That sounds like a smart approach! Having docs generated from your code makes it super easy to keep everything updated.