Thursday, September 21, 2023
HomeHealthFirst Code... Then Infrastructure as Code... Now Notes as Code!

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


First, let me say how we take notes and what instruments we use are admittedly a private desire and choice. Hopefully, we are doing it, nevertheless!

Most of us are creatures of behavior and luxury – we would like it easy and efficient. After we put that developer hat on as a part of our DevOps/SRE or AppDev roles it’s optimum after we can mix our code growth atmosphere, or IDE, with a device that we take notes in. I’m certain most of us are utilizing Microsoft’s Visible Studio Code app as we write Python or Go-based scripts and functions throughout our community programming and automation work. I in all probability knocked out 4,500 traces of Python in help of the CiscoLive Community Operations Heart (NOC) automation earlier this summer season and VS Code was integral to that.

Jason Notes as CodeMicrosoft Visible Studio Code with a CiscoLive NOC Python Script

You’re in all probability acquainted with VS Code’s sturdy integration with git out of your native growth atmosphere and the flexibility to synchronize with distant GitHub repositories. It’s a terrific characteristic to make sure model management, present code backup storage, and encourage collaboration with different builders.

Jason Notes as CodeGitHub with a CiscoLive NOC Software program Repository

I used to be inspired to search out an extension to VS Code that follows the idea of ‘Docs as Code’. If you happen to’re not acquainted, I’d encourage you to observe my esteemed Developer Relations colleague, Anne Mild, who’s main a lot innovation on this house. Anne describes this idea in her GitHub repo.

The extension I exploit known as Dendron. It’s extra formally generally known as an open-source doc administration system. It permits for hierarchical documentation and note-taking. It makes use of the identical, acquainted markdown idea for textual content formatting, doc linking and picture references, as you’ll use with GitHubWebex messaging app or Webex API. You may journal and have your ideas organized in every day buckets. Doc templates are supported. I discover the provided assembly notes template as fairly helpful and extensible. As a proof of Dendron’s flexibility, I wrote this weblog in Dendron earlier than passing over to the publication group!

Jason Notes as CodeVS Code with Dendron Extension: Notice Taking Panel with Preview

I admire the hierarchical mannequin of taking notes. I’ve sections for my group notes, my tasks, the companions and prospects I’m working with, and one-on-one assembly notes. The hierarchy works down from there. As an illustration, this be aware is saved within the VS Code workspace for Dendron, and its vault, as ‘MyProjects.blogs.Notes as Code.md’.  I even have a ‘MyProjects.PiK8s.md’ for a Kubernetes atmosphere on a cluster of Raspberry Pis – extra on that quickly!

Dendron is able to effectively and rapidly looking and managing tens of 1000’s of notes. After I end a challenge, I can refactor it into a distinct hierarchy for archive. The hyperlinks inside the unique be aware are re-referenced, so I don’t lose continuity!

I’m not prepared to do that refactor simply but, however right here’s a screensnap of it confirming the motion of the be aware throughout hierarchies. I are likely to put accomplished tasks in a ‘zARCHIVE’ department.

Jason Notes as CodeDendron Extension Utilizing Doc Refactor Characteristic

Dendron additionally helps superior diagramming with the mermaid visualization syntax. This subsequent picture is a linked screen-capture of the Dendron writing panel adjoining to the preview panel the place I imagined a workflow to get this weblog posted.

Jason Notes as CodeDendron Markdown with Preview Exhibiting mermaid Circulation Chart

Community protocol and software program inter-process communication will be documented as sequence diagrams additionally! Right here’s my tongue-in-cheek illustration of a DHCP course of.

```mermaid
sequenceDiagram
participant Consumer
participant Router
participant DHCP Server
Consumer->>Router: I want my IP Tackle (as broadcast)
Router->>DHCP Server: (forwarded) Get subsequent lease
DHCP Server-->>Router: Here is 192.168.1.100
Router-->>Consumer: You good with 192.168.1.100?
Consumer->>Router: Sure, thanks
Router->>DHCP Server: We're all set!
```

The markdown and preview behind the scenes regarded like this…

Dendron Markdown with Preview Exhibiting mermaid Sequence Diagram

So, How Can I Use This?

An efficient approach of utilizing VS Code with Dendron could be in live performance with the notetaking and documentation you do on your git repos. Since Dendron notes are successfully textual content, you possibly can sync them together with your git repo and distant GitHub publication as your README.md recordsdata, LICENSE.md and CONTRIBUTING.md, which ought to make up the muse of your documented challenge on GitHub.

I hope you discover the effectivity of utilizing Dendron in VS Code together with the writing of Python script in the identical as useful as I do!

Associated sources

If you happen to’re occupied with some extra Cisco DevNet sources round challenge documentation, take into account this Code Trade Repo Template on your challenge – it doesn’t even must be submitted to Cisco. The primary factor is to prepare and template cheap data for others to devour and be constant.

You may also try Cisco Code Trade. There you’ll discover and collaborate on curated GitHub tasks to jumpstart your work with Cisco platforms, APIs, and SDKs.


We’d love to listen to what you assume. Ask a query or depart a remark under.
And keep related with Cisco DevNet on social!

LinkedIn | Twitter @CiscoDevNet | Fb | YouTube Channel

Share:



RELATED ARTICLES

LEAVE A REPLY

Please enter your comment!
Please enter your name here

Most Popular

Recent Comments