Where do my docs go?

#documentation #docs #wiki #writing

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.

Approaches to managing docs

This section post was inspired by reading this post on dev.to - Where should you put the documentation? by @nicoespeon.

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.

Platforms for docs

Ideas for places to host your code documentation.

I've included links to my own projects where possible.

Wiki

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.

Example:

https://github.com/MichaelCurrin/instant-website/wiki

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.