A better class of note

19 May 2017

This article covers what I think is a good way of taking notes, keeping track of them, and publishing them so that others can benefit from them or comment on your approach.

We often use notes to track what we have to do or have done. They might be in paper form or electronic text files. They document how we achieved our goal: the helpful URLs that put us on the right track, error and warning messages that were encountered and how they were resolved, etc. However, notes can quickly become intractable with recorded error and/or warning messages and unfathomably long URLs or, worse, they get lost.

How often have you had a feeling of deja vu? I have done this before and I know I took notes... But where are they now? At other times you remove something, only to wish you had left it in: an error/warning message or a URL that could have solved a subsequent problem.

You can resolve most of these problems by migrating to GitHub gists as I have done, or to one of the very similar services provided by BitBucket's snippets or GitLab's snippets, all of which do very similar things.

Notes can be public or private (you need the right URL to access a note, and so you can share it with collaborators who could become contributors). If you make the notes public they could help others, or others might give additional insight, alternative views or approaches via a commenting feature. The documents are versioned so you can recover previous content (you could download as a git repository if you wished).

You can use plain text or markdown, where the document is marked up to be rendered at the server end. As a simple example, beginning a line with "# My title" would be the equivalent of using "<h1>My title</h1> in html but it's nowhere as near as tedious as writing raw html and you can read the document offline as a plain text document and do not need a browser as you would for html.

Here are some gists that I keep on GitHub using markdown: setting up a CentOS 7 VM on a Mac with Sierra using Virtual Box, and notes I use for delivering Software Carpentry git lessons.  So, if you already have accounts on GitHub, BitBucket or GitLab trying using gists/snippets.