First, let me say how we take notes and what instruments we use are admittedly a private choice and choice. Hopefully, we are doing it, nonetheless!
Most of us are creatures of behavior and luxury – we wish it easy and efficient. Once 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 instrument 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 purposes throughout our community programming and automation work. I most likely knocked out 4,500 strains of Python in help of the CiscoLive Community Operations Middle (NOC) automation earlier this summer season and VS Code was integral to that.
Microsoft Visible Studio Code with a CiscoLive NOC Python Script
You’re most likely 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 an important function to make sure model management, present code backup storage, and encourage collaboration with different builders.
GitHub with a CiscoLive NOC Software program Repository
I used to be inspired to seek out an extension to VS Code that follows the idea of ‘Docs as Code’. When you’re not acquainted, I’d encourage you to comply with 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 take advantage of is named Dendron. It’s extra formally often called 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 GitHub, Webex messaging app or Webex API. You’ll be able to journal and have your ideas organized in day by day buckets. Doc templates are supported. I discover the equipped 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 workforce!
VS Code with Dendron Extension: Be aware Taking Panel with Preview
I admire the hierarchical mannequin of taking notes. I’ve sections for my workforce notes, my tasks, the companions and clients I’m working with, and one-on-one assembly notes. The hierarchy works down from there. As an illustration, this observe 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 out and managing tens of hundreds of notes. After I end a venture, I can refactor it into a special hierarchy for archive. The hyperlinks inside the authentic observe 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 observe throughout hierarchies. I are inclined to put accomplished tasks in a ‘zARCHIVE’ department.
Dendron Extension Utilizing Doc Refactor Function
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.
Dendron Markdown with Preview Exhibiting mermaid Move Chart
Community protocol and software program inter-process communication might be documented as sequence diagrams additionally! Right here’s my tongue-in-cheek illustration of a DHCP course of.
```mermaid sequenceDiagram participant Shopper participant Router participant DHCP Server Shopper->>Router: I want my IP Handle (as broadcast) Router->>DHCP Server: (forwarded) Get subsequent lease DHCP Server-->>Router: This is 192.168.1.100 Router-->>Shopper: You good with 192.168.1.100? Shopper->>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 manner of utilizing VS Code with Dendron can be in live performance with the notetaking and documentation you do in your git repos. Since Dendron notes are successfully textual content, you’ll be able to sync them along with your git repo and distant GitHub publication as your README.md information, LICENSE.md and CONTRIBUTING.md, which ought to make up the muse of your documented venture 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 helpful as I do!
Associated assets
When you’re concerned with some extra Cisco DevNet assets round venture documentation, take into account this Code Change Repo Template in your venture – it doesn’t even must be submitted to Cisco. The primary factor is to arrange and template affordable data for others to eat and be constant.
You can too take a look at Cisco Code Change. 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:
