This lesson's interactive features are locked, please to keep using them
How to Document
As far as creating documentation goes, there are 2 main approaches:
- Manually write documentation
- Use a tool to generate documentation
Obviously, the first approach is easier to get going with if you have a small API, but as the system grows, it can be really hard to keep the documentation up to date.
Incorrect documentation is worse than no documentation.
At least when there is no documentation, your clients will reach out and ask for clarification. When the documentation is incorrect, it can lead to a lot of wasted time and frustration.
Manually Writing Documentation
When I've worked on smaller teams, we've generally opted to write our documentation in Markdown files and host them on GitHub. This is a great way to get started because Markdown is a simple format that is easy to write and easy to read.
Some Automated Tools to Be Aware Of
I've also written and consumed APIs that have used:
Okay, but What Should I Do Now?
I recommend writing documentation for your personal projects in Markdown files and storing them alongside the rest of your code in Git. Your project's README.md file is a great place to start, but it's also common for the README.md file to link to a /docs folder that contains more detailed documentation. The benefits are:
- It's easy to get started writing docs
- The documentation lives alongside your code, so it's easy to keep it up to date
- You'll learn Markdown, which is a great skill to have
- GitHub/GitLab will render your Markdown files for you, so your docs will look great
Click to play video