TIP: Using LOCAL_NOTES.md

I tweeted few months ago about a productivity hack of mine of keeping a LOCAL_NOTES.md file inside of the projects I work with. I never wrote more about it but as I’ve noticed using these even more lately I decided it was time to document this better.

Lowering Cognitive Load

I’m a big believer in collaborative project management tools like ticketing systems, intranets, and wikis. When you work with a team, it’s crucial to get as much tacid knowledge into these tools as possible. However, there’s one downside of using these kind of tools; the data you put in needs to be as well formatted and labelled as possible. And this is where personal note systems come in.

Whatever your personal note taking system is, it’s important to have at least one place for quick and unorganized thoughts. This lowers the barrier of just burbing the idea or thought out of your mind, as fast and painlessly as possible. Lowering the cognitive load of making notes for yourself can help immensely when you don’t want to break up your concentration of whatever task you’re doing but still write down random notes.

For Your Eyes Only

I have a permanent ignore for LOCAL_NOTES.md for every single repository I create. I only create the file if I feel the need for document something personal that I don’t want to document anywhere else, or if I for example want to plan out how I’m going to break an upcoming task into smaller chunks without writing anything formal in the related ticket.

As these notes are private, you should feel free to put down whatever in whatever form you feel like (with certain constraints, obviously). Again, the point is to lower your barrier to write down your thoughts regarding the project, whatever they may be.

Sometimes you’ll find that you’ve written something that maybe shouldn’t be in this note anymore. If you catch yourself asking this question, don’t hesitate but yank that text out of the file and put it somewhere better suited. These kind of notes like all wikis and intranets need gardening every now and then.

What Not to Do

You should never ever strore anything valuable or secret in these kind of notes. If you want to store things like local passwords or API keys, just use a password manager like you do for everything else.

Documentation, even if it’s unfinished or for your personal use, doesn’t belong to these notes either. If it’s raw or unfinished, put it in a ticket or a wiki page with a WIP -label instead. If it’s something you wrote for yourself because it cannot for some reason go into the the official docs, put it in intranet or a wiki so you can link it to colleagues if needed, and so you can have an example of what’s missing or wrong in the public docs in case there’s a discussion about it at some point. It’s good to have these kind of things out of your head for others to see.