This post is for you if you're writing technical documentation for your repos for your personal projects or your organization and you feel like docs get out of control.
Below are my main take-aways from the post.
You need one place for your docs. Or at least make a primary obvious place for someone to add/update docs and to find docs and then communicate. Otherwise docs will appear all over the place and docs get more spread out and chaotic over time.
Out of date docs need to be updated or deleted. If it unreliable and messy now, people won't want to read or update it.
If other teams ask your team for the same info over and over, that is a sign that the info should be in a doc which can be read outside your team and that the documentation should be accessible (see previous points).
When someone new joins your team and uses your onboarding docs, ask them to make suggestions to improve them. If there is anything out of date or obscure especially for a newcomer to read, they'll be able to pick that up and change the docs.
Ideas for places to host your code documentation.
I've included links to my own projects where possible.
I like using GitHub's Wiki feature as it is paired with code for a repo, uses markdown (and other formats) and it easy for non-developers to update.
This is especially good for an API spec to work towards for the project team and for other teams (as they know what the API will look like when it is finished.
On GitHub, if you enable editing of your repo, a Wiki is accessible for anyone with a GH account to edit. Unfortunately its there is no review process or Pull Requests, so there is risk of malicious behavior. Don't worry, a Wiki is actually a standalone repo, so you can always clone it and rollback changes and then push.
Store docs in your GitHub repo.
At the least, add a
README.md file, but a directory called
docs is great for multiple pages that don't clutter the top-level directory.
I've included examples below of a sample structure. The Python one is a template with minimal content.
A docs website built around a GH repo (e.g. using Jekyll or Hugo).
For your documents, spreadsheets, PDFs, images, CSVs and more. Whether for yourself or an org.
This is a project by Atlassian, who makes Jira. You can have a self-hosted confluence site on your org's domain. e.g.
This was recommended in the post as a powerful for documentation so I am going to look into this.