First Code… Then Infrastructure as Code… Now Notes as Code!

First, let me say how we take notes and what tools we use are admittedly a personal preference and decision. Hopefully, we are doing it, however!

Most of us are creatures of habit and comfort – we want it simple and effective. When we put that developer hat on as part of our DevOps/SRE or AppDev roles it’s optimal when we can combine our code development environment, or IDE, with a tool that we take notes in. I’m sure most of us are using Microsoft’s Visual Studio Code app as we write Python or Go-based scripts and applications during our network programming and automation work. I probably knocked out 4,500 lines of Python in support of the CiscoLive Network Operations Center (NOC) automation earlier this summer and VS Code was integral to that.

Microsoft Visual Studio Code with a CiscoLive NOC Python Script

You’re probably familiar with VS Code’s strong integration with git from your local development environment and the ability to synchronize with remote GitHub repositories. It’s a great feature to ensure version control, provide code backup storage, and encourage collaboration with other developers.

GitHub with a CiscoLive NOC Software Repository

I was encouraged to find an extension to VS Code that follows the concept of ‘Docs as Code’. If you’re not familiar, I’d encourage you to follow my esteemed Developer Relations colleague, Anne Gentle, who is leading much innovation in this space. Anne describes this concept in her GitHub repo.

The extension I use is called Dendron. It is more officially known as an open-source document management system. It allows for hierarchical documentation and note-taking. It uses the same, familiar markdown concept for text formatting, document linking and image references, as you would use with GitHub,  Webex messaging app or Webex API. You can journal and have your thoughts organized in daily buckets. Document templates are supported. I find the supplied meeting notes template as pretty useful and extensible. As a proof of Dendron’s flexibility, I wrote this blog in Dendron before passing over to the publication team!

VS Code with Dendron Extension: Note Taking Panel with Preview

I appreciate the hierarchical model of taking notes. I have sections for my team notes, my projects, the partners and customers I’m working with, and one-on-one meeting notes. The hierarchy works down from there. For instance, this note is stored in the VS Code workspace for Dendron, and its vault, as ‘MyProjects.blogs.Notes as Code.md’.  I also have a ‘MyProjects.PiK8s.md’ for a Kubernetes environment on a cluster of Raspberry Pis – more on that soon!

Dendron is capable of efficiently and quickly searching and managing tens of thousands of notes. When I finish a project, I can refactor it into a different hierarchy for archive. The links within the original note are re-referenced, so I don’t lose continuity!

I’m not ready to do this refactor just yet, but here’s a screensnap of it confirming the movement of the note across hierarchies. I tend to put completed projects in a ‘zARCHIVE’ branch.

Dendron Extension Using Document Refactor Feature

Dendron also supports advanced diagramming with the mermaid visualization syntax. This next image is a linked screen-capture of the Dendron writing panel adjacent to the preview panel where I imagined a workflow to get this blog posted.

Dendron Markdown with Preview Showing mermaid Flow Chart

Network protocol and software inter-process communication can be documented as sequence diagrams also! Here’s my tongue-in-cheek representation of a DHCP process.

```mermaid

sequenceDiagram

participant Client

participant Router

participant DHCP Server

Client->>Router: I need my IP Address (as broadcast)

Router->>DHCP Server: (forwarded) Get next lease

DHCP Server-->>Router: Here's 192.168.1.100

Router-->>Client: You good with 192.168.1.100?

Client->>Router: Yes, thank you

Router->>DHCP Server: We're all set!

```

The markdown and preview behind the scenes looked like this…

Dendron Markdown with Preview Showing mermaid Sequence Diagram

So, How Can I Use This?

An effective way of using VS Code with Dendron would be in concert with the notetaking and documentation you do for your git repos. Since Dendron notes are effectively text, you can sync them with your git repo and remote GitHub publication as your README.md files, LICENSE.md and CONTRIBUTING.md, which should make up the foundation of your documented project on GitHub.

Source: cisco.com