Writing documentation for yourself

It sounds weird to write documentation for yourself, right?

No!

Imagine a project you are working on. You finished it, deployed and haven’t touched it for few months.

Now, after this long period of time, you decided to get back to it, make some improvements or fixes, update some packages.

Maybe you’ve changed your computer since then, reinstalled operating system, or bought a new computer!

Now, you need to set up project locally to make some quick fixes, that on themselves should take from 30 minutes to couple hours max.

But here is a problem. You totally forgot how to set things up to run it locally.

Or you forgot how you deploy it.

If you haven’t write step-by-step documentation that includes what software you need to have, how to set it up (credentials, paths, etc), how to make changes and deploy them in production, setting things up will be a huge overhead compared to the time you needed to make changes.

We’ve all being there, we’ve all done that. At least I did. Many times.

What I recommend to do.

Have a CONTRIBUTING.md in the root of your project.

Describe how to set local development environment.

This part should include installation of databases, creating credentials, installing interpreters and virtual environments, creating demo data or importing production or special snapshot.

Describe what are steps to check code is ready to be pushed to the repo.

How to run tests, how to check code style, how to create merge request, how to check it was merged and make sure that production server is working.

I often describe it as commands that I need to run to recreate development environment.

I prefer not to use bash scripts for that because it takes a noticeable amount of time to handle errors.

It’s not worth it in the time spent, because local development environment changes quickly.

New versions of operating systems and tools – these things introduce changes that cannot be possibly handled automatically since they are being run rarely.

Also, the goal is to help to setup development environment, not completely automate it.

If you plan to support project for a long time – you have to spend some time on writing set-up docs and make sure it works fine, by following your own documentation and recreating environment on from the start.

If you think you will never get to this project again – just write those docs anyway. Make it a habit. You’ll be surprised how many times I was getting back to projects I thought I would never touch again.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.