Have you read Alice’s Adventures in Wonderland? This is one of my favorite childhood books. The Cheshire Cat, known for its distinctive mischievous grin, and The Mad Hatter, an impolite hatter who lives in perpetual tea-time. At Christmas time my family and I sit and read the book in the evening.
The tiny bottles and cakes are always my wife’s favorite part of Alice in Wonderland. The ‘Eat Me’ cakes are magical cakes in Wonderland that have a very strange effect- they make the eater grow enormous. ‘Drink Me‘ potion is a magical liquid in Wonderland that has an unusual effect to make the drinker shrink in size. When Alice became trapped in the White Rabbit’s home, he (The White Rabbit) and his comrades threw pebbles into the house which became soft sponge cakes, making Alice shrink down to her normal size.
Down the Rabbit-Hole without a clue
The events of Alice eating the “Eat Me” cake and “Drink Me” potion are crucial to the story itself, (And of course there, wouldn’t be a story without Alice consuming these items). Alice is repeatedly told to consume something without being told what it is, such as the “Drink Me” bottle and “Eat Me”.Alice, without thinking twice, she consumes these. Has this ever been the case when you have copied something from Stack Overflow, or cloned a GitHub repo with no README (or an incomplete one) and tried to run the code, and it’s not working how you anticipated (failed to run) or even made matter worst off? Often the case for this is lack of documentation or “TL;DR“. Which is a great reason to make a clear and solid README – you do not want a user to consume something, without being told what it is or does.
Advice from a Caterpillar (its not just about how awesome your code is)
I started using GitHub roughly four years ago. At that time, while I had heard of GitHub and had made and account, I admit that I really did not yet have a clue what to do with it or what it was really for. I looked around for a few months, perused over some code examples and some projects – from individual contributors and from company-like open source community projects. But it wasn’t until I started treating my ‘infrastructure as code’ (IaC) that I really got how to use it, how powerful source control could really be, and it soon became the beginning for my infrastructure as code implementation. When this was finally combined with network automation, QA, adds, moves, and changes to a network, it was easy to see the business value it added — far better communication, collaboration and feedback within and across IT development and operations teams.
However my personal repo (which was public) was still little to be desired. I had uploaded a few code examples (mostly python) for network automation (mostly testing, deployments etc.), and had uploaded a few rough ideas and templates just to keep track of what I had done and so I could say I had an account with some code on it. But it wasn’t until I started with Cisco DevNet that I really thought about what I was uploading and how this was presented to the DevNet community, to the open source community, or for that matter to anyone that fell into my account. This became of greater importance this year when DevNet launched Cisco Code Exchange. We specify in the Code Exchange guide that all submissions require a clear README and contributing process.
The Mock Turtle’s story (you found the repo now what?)
Like you, I have found some great ideas, repos, and code on GitHub – there are some really creative and awesome people out there grinding out ideas on just about everything! Recently, I was looking to fix a file issue. I was not sure how I would do this until, at the top of a Google search I found a repo with a great README explaining what the project and code were for. A quick git clone, install of the requirements, and my file was fixed! I could carry on with my project. That is a great example of how it should be done.
By looking at projects from people I follow on GitHub, I discovered I could make my own projects, repos, and code examples more useful by following a few simple steps. (Not all may apply for your use case (ymmv).
Project Name – Add some information about your project, or overview that explains to the reader what the project is all about.
Motives – A brief overview of the reason behind the creation of the project. This should explain why the project exists. In my case I might be using it for a webinar (like the ones we did recently for NetDevOps Live, a DevNet Express event or for a Cisco Live session.
Status – If this is a work in progress, you are adding more features, pending review, etc. , then make the user/reader aware of this. They may wish to contribute with you (two heads are better than one!)
Installation – This can be a simple ‘How to” with “pip install” for the user to clone and follow the steps to get their dependencies for their local dev environment. This is good place to note any caveats for different operating systems.
References – If the intention of the code is to work with device API’s, links to the API’s documents are always useful.
Alice’s Evidence (examples, screenshots, and more)
I always add examples, such as expected outcomes, or issues that may occur in code blocks. As of late I started doing more code snips so the user saw just the results, certainly if the output being generated was very verbose. Then further to this, I saw some folks adding a Terminal session recorder and embedding a “svg” / “gif” or “png” to the README showing the code being run, deployed, and results. This for me is great, being a visual person.
There are a few ways to do this. The first one I used was Asciinema. You can install this with “pip” or “Homebrew.” It’s quick to get up and running – the file is saved as a “.cast” format/extension for which you can use asciicast2gif. You can use “asciicast2gif” through official asciicast2gif Docker image (automated build on Docker Hub from this repository).
The next one I use is termtosvg – this installed via pip again. This saves the file in a “svg” format/extension (just beware that embedding this “svg” file in the GitHub README can be troublesome). Both of these Terminal session recorders offer a range of settings to alter the recording such as template, speed, length etc.
Putting this on GitHub is pretty simple, you insert this like any other image. For example in this SDWAN repo i have been working on this week. I pushed the “svg” file to my repo and then added this in the repo using the relative path.
Join DevNet
If you haven’t already done it, please join our community. Get your free DevNet account for access to all these resources, plus all the fun and professional growth that goes along with learning new skills and putting them to good use.
We’d love to hear what you think. Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!
Twitter @CiscoDevNet | Facebook | LinkedIn
Visit the new Developer Video Channel
CONNECT WITH US