Developers: Are You Taking 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.

I hope you find the efficiency of using Dendron in VS Code along with the writing of Python script in the same as beneficial as I do!

Related resources

If you’re interested in some more Cisco DevNet resources around project documentation, consider this Code Exchange Repo Template for your project – it doesn’t even have to be submitted to Cisco. The main thing is to organize and template reasonable information for others to consume and be consistent.

You can also check out Cisco Code Exchange. There you’ll find and collaborate on curated GitHub projects to jumpstart your work with Cisco platforms, APIs, and SDKs.

We’d love to hear what you think. Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!

LinkedIn | Twitter @CiscoDevNet | Facebook | YouTube Channel

Share: