Notes on "Notes" (new blog post format)

Table of Contents

2020 is almost upon us. Time for reflection and forward looking visions. Some of the phrases that have been surfacing as resolutions for myself are,

What I want to do…

Do more writing
Document everything
Automate everything
Share everything
Learn more things
Learn in public
Use Git/GitHub
…

Some of those are overly general. Phrases like "foo more bar, and foobar everything" don't really specify an actionable plan, but, they do at least hint at something good to do. "Learning in public" is an intriguing idea, … could be good conversation starter at a party … for nerds. "Use Git/GitHub", should probably be followed with "for everything".

Something that is specific and related to that list is a new blog post format that I want to try for 2020, "Notes". "Notes" connotes brevity and specificity. The "gist" of things. Put those out in public!

Why?

I enjoy writing especially when the result is something that is helpful to someone, … anyone, including myself. The sentiment of "what I want to do" is document and organize what I'm working on/with and share that with the world. This also gives me an accessible reference for the things I'm learning/re-learning(for the 10th time).

“Notes”?

This will be "micro blogging" via GitHub Gists. The idea is to post snippets of well formatted, information, on-the-fly, while working. And, do this in a way that is minimally disruptive to workflow. Gists will be created from a templates with metadata, and a nifty looking VS-code plugin called GistPad.

The idea is to post snippets of well formatted, information, on-the-fly, while working. And, do this in a way that is minimally disruptive to workflow.

The Gists will include,

short description
code blocks
command line sessions
screenshots, images
examples
maybe short screen-casts

A single problem, idea or action per Gist.

There will be a Master Index Page organizing listings by category for all of the notes.

Categories would include,

bash, powershell …
git, GitHub …
python, javascript, julia …
docker, kubernetes
Linux, WSL …
tensorflow, pytorch …
…

Categories to be added as they arise. Accumulating as a mix of system-administration (DevOps), programming, ML/AI, Science, and brief HowTos etc..

The accumulated "notes" could form the basis of longer documents about the different catagories.

Success with this will depend on automation! It needs to go something like; Idea/problem (while working in vscode) –> create markdown along with snippets , commands etc. plus metadata –> create Gist –> update master index –> trigger post generation –> notifications, tweet etc. All of that with one command after composing the Gist in vscode.

What could go wrong?

If it breaks "flow" then it will not work.
If I get too "involved" in the notes then it will be too disruptive. That means I have to resist rambling on with needless chatter, like I'm doing right now …
Need to have a publishing system API for automation (we are transitioning to an API supported publishing system "real soon now" … I hope).
It has to "spark joy"! The good feeling from putting up more helpful posts has to be self rewarding. If it becomes a tedious chore then it won't work.
Technical difficulties? Yes, there could be some of those. I haven't worked out all of the details yet.
I could get "push-back" from colleagues and readers that it's just not helpful.
It needs to become a habit. After I get the functional details completely worked out I'll commit to doing it for at least a month before I evaluate effectiveness. We'll see how it goes!

I will still be doing longer posts. The in depth HowTos, hardware testing, etc. will continue. I enjoy that!