loading...
Cover image for Where do my docs go?

Where do my docs go?

michaelcurrin profile image Mike ・3 min read

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

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.

GitHub docs

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.

Example:

https://github.com/MichaelCurrin/py-project-template/tree/master/docs

PY docs

https://github.com/MichaelCurrin/instant-website/tree/master/docs

Docs folder

Docs site

A docs website built around a GH repo (e.g. using Jekyll or Hugo).

Example:

https://michaelcurrin.github.io/instant-website/

docs site

https://michaelcurrin.github.io/docsify-js-template/#/

docsify

Google Drive

For your documents, spreadsheets, PDFs, images, CSVs and more. Whether for yourself or an org.

https://www.google.com/drive/

Confluence

This is a project by Atlassian, who makes Jira. You can have a self-hosted confluence site on your org's domain. e.g. confluence.foo.com

https://www.atlassian.com/software/confluence

Notion

This was recommended in the post as a powerful for documentation so I am going to look into this.

https://www.notion.so/

Credits

Photo by Garmin Bao on Unsplash

Posted on by:

michaelcurrin profile

Mike

@michaelcurrin

I'm a self-taught dev focused on websites and Python development. My friends call me the "Data Genie". When I get bored, I find tech to read about, write about and build things with.

Discussion

pic
Editor guide