Devnet 1069

Oh you've built the best product in
the world? Come back when you

have proper documentation
Conor Murphy
Technical Solutions Architect – Data Centre
DEVNET-1069
12 things to include in your
documentation. You won't believe
what number 9 is!
Conor Murphy
Technical Solutions Architect – Data Centre
DEVNET-1069
Cisco Webex Teams
Questions?
Use Cisco Webex Teams to chat
with the speaker after the session
How
1 Find this session in the Cisco Events Mobile App
2 Click “Join the Discussion”
3 Install Webex Teams or go directly to the team space
4 Enter messages/questions in the team space
DEVNET-1069 © 2020 Cisco and/or its affiliates. All rights reserved. Cisco Public 4
"If it isn't documented, it doesn't
exist."
http://www.mikepope.com/blog/DisplayBlog.aspx?permalink=1680
https://web.archive.org/web/20071113213614/http://www.amazon.com/gp/plog/post.html/ref=cm_blog_pl?ie=UTF8&pt=personalBlog&aid=PlogMyCustomersAg
ent&ot=customer&pd=1164175937.423&pid=PMCA1J3TWE84RTHQXat1164175038&iid=A1J3TWE84RTHQX
https://web.archive.org/web/20070227072817/https://www.b-list.org/weblog/2007/01/22/choosing-javascript-library
https://www.youtube.com/watch?v=W9EwAg4Mu8Y
https://www.digitalocean.com/currents/october-2018/
Acknowledgements
opinions
things to point out tools
examples
readme
reference
cookbook
types of user guide
documentation blogpost
whitepaper
It's not just the contents, it's also how it
looks
• Depending on the project, your
documentation might include some or all of
the following components: An introduction
should show a very short overview of what
can be done with the product, using one or
two extremely simplified use cases. This is
the thirty-second pitch for your project. A
tutorial should show some primary use cases
in more detail. The reader will follow a step-
by-step procedure to set-up a working
prototype. An API reference is typically
generated from the code (see docstrings). It
will list all publicly available interfaces,
parameters, and return values.
https://docs.python-guide.org/writing/documentation/
Depending on the project, your documentation might
• Depending on the project, your include some or all of the following components:
documentation might include some or all of
the following components: An introduction • An introduction should show a very short
should show a very short overview of what overview of what can be done with the product,
using one or two extremely simplified use cases.
can be done with the product, using one or
This is the thirty-second pitch for your project.
two extremely simplified use cases. This is
the thirty-second pitch for your project. A • A tutorial should show some primary use cases in
tutorial should show some primary use cases more detail. The reader will follow a step-by-step
in more detail. The reader will follow a step- procedure to set-up a working prototype.
by-step procedure to set-up a working • An API reference is typically generated from the
prototype. An API reference is typically code (see docstrings). It will list all publicly
generated from the code (see docstrings). It available interfaces, parameters, and return
will list all publicly available interfaces, values.
parameters, and return values.
https://docs.python-guide.org/writing/documentation/
markdown lightweight and easy-to-use syntax
for styling
https://en.wikipedia.org/wiki/Markdown
https://guides.github.com/features/mastering-markdown/
tool that analyzes source code to
linting flag programming errors, bugs,

stylistic errors, and suspicious
constructs
https://en.wikipedia.org/wiki/Lint_(software)
This example uses Visual Studio
Code with the Markdown Preview
Enhanced extension
Example Markdown linter extension
"First line in file should be a top level

heading"
Copy/Pasting – Need to be easy to
copy and paste. Makes it hard
when you have prompt with folder,
$ sign etc
a few extra tips on Editing vs Copy/Paste – Make it

clear when something needs to be
formatting edited and can't just be copy and
pasted e.g. editing a file
Expected Output – It's always

helpful to know what the output
should be when running a
command
"79 percent . . . always scanned
any new page . . . ; only 16
percent read word-by-word"
https://www.nngroup.com/articles/how-users-read-on-the-web/
Markdown Tools and References
• https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
• https://www.markdownguide.org/basic-syntax/
• https://github.github.com/gfm/#introduction
• https://code.visualstudio.com/docs/languages/markdown
• https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-
preview-enhanced
• https://medium.com/@tracymakes/five-tips-for-improving-your-technical-writing-
and-documentation-47353723c8a7
• https://stoplight.io/blog/writing-documentation-when-you-arent-a-technical-
writer-part-one-ef08a09870d1/
• https://brainhub.eu/blog/writing-good-documentation-open-source-library/
What To Include In
A Readme?
https://opensource.com/article/17/8/doc-driven-development
https://www.researchgate.net/publication/318733467_Application_Programming_Interface_Docu
mentation_What_Do_Software_Developers_Want
Suppose you have to get into a new API: Which question comes up first?
Which information resources do you use (a) to get started or (b) to

solve programming issues later on when working with an API?
You have to get into a new API. What are the first steps you take?’
https://www.researchgate.net/publication/318733467_Application_Programming_Interface_Documentation_What_Do_Software_Developers_Want
Release Notes
https://github.com/CiscoDevNet/webexteamssdk/releases
How Can People
Contribute?
https://github.com/atom/atom/blob/master/CONTRIBUTING.md
https://github.com/rails/rails/blob/master/CONTRIBUTING.md
How Do I License
My Project?
https://choosealicense.com
https://help.github.com/en/github/creating-cloning-and-archiving-repositories/licensing-a-repository
https://choosealicense.com/licenses/mit/
Software Licenses
Public
domain & Copyleft Permissive Noncommercial Proprietary Trade secret
equivalents
• Grants rights for

• Grants use rights
• Grants use noncommercial • Traditional use • No
• Must disclose source
Descriptio • Grants all rights use only of copyright information
code
n rights • Right to • May be • No rights need made
• Modifications must
relicense combined with be granted public
use same license
copyleft
Software Creative {roprietary Private,

GNU General Public Java Research
License Commons MIT, Apache software, no internal
License (GPL) Library (JPL)
Example (CC) public license software
https://en.wikipedia.org/wiki/Copyleft
https://en.wikipedia.org/wiki/Copyright
https://en.wikipedia.org/wiki/Permissive_software_license
MIT License (Permissive)
GNU GPLv3 (Copyleft)
Apache License 2.0 (Permissive)
https://en.wikipedia.org/wiki/MIT_License
https://www.gnu.org/licenses/gpl-3.0.en.html
https://www.apache.org/licenses/LICENSE-2.0
license legal framework that allows for
pieces of software with
compatibility different software licenses to be
distributed together
https://en.wikipedia.org/wiki/License_compatibility
https://github.com/github/licensed
Licensing Tools and References
• https://choosealicense.com
• https://help.github.com/en/github/creating-cloning-and-archiving-repositories/licensing-a-
repository
• https://en.wikipedia.org/wiki/Software_relicensing
• https://github.com/github/licensed
• http://www.catb.org/~esr/Licensing-HOWTO.html#changing
• https://en.wikipedia.org/wiki/MIT_License
• https://www.gnu.org/licenses/gpl-3.0.en.html
• https://www.apache.org/licenses/LICENSE-2.0
A few extra tips on
documentation
vagrant
demo docker
environments jupyter notebooks

hosted (SaaS)
How to draw an owl
1. Draw two circles 2. Draw the rest of the owl

quickstart i.e hello world
101, 201, 301
use cases and examples
don't forget the
201 reference and user guide
Waterfall
Design
Build
Release
Time
Design, Build, Design, Build, Design, Build,

Release Release Release
Agile
documentation "when you modify code, get in the
development habit of editing comments and
related documentation"
lifecycle
https://blog.digitalocean.com/documentation-as-an-open-source-practice/
pair programming
duo documentation?
the driver codes while the
the observer reviews each line of code
as it is typed
https://en.wikipedia.org/wiki/Pair_programming
"If a tree falls in a forest and no
one is around to hear it, does it
make a sound?"
George Berkley
" [Tweet and Blog.] Answer the
promote your effort questions on StackOverflow and

Quora. Talk to people in Facebook
but don't spam Groups. Submit a link to
HackerNews and Reddit. And ask
Newsletters to post your project."
https://www.freecodecamp.org/news/what-i-learned-from-an-old-
github-project-that-won-3-000-stars-in-a-week-628349a5ee14/
https://blogs.cisco.com/developer/ucs-hx-veeam-powershell
ReadMe Tools and References
• https://github.com/matiassingers/awesome-readme
• https://gist.github.com/PurpleBooth/109311bb0361f32d87a2
• https://help.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors
• https://docs.python-guide.org/writing/documentation/
• https://www.writethedocs.org/
• https://www.writethedocs.org/videos/portland/2019/
• Example READMEs
• https://github.com/CiscoDevNet/code-exchange-repo-template/tree/master/manual-sample-repo
• https://github.com/movinalot/dcloud-cisco-hyperflex-veeam-integration
What's Next?
tutorials video + text transcripts
https://stripe.com/docs/payments/accept-a-payment-charges
pycco produces HTML that displays your
comments alongside your code
https://pycco-docs.github.io/pycco/
https://www.docslikecode.com/about/
“I apologize for such a long letter - I
didn't have time to write a short
one.”
Mark Twain
where to host
additional
documentation?
https://readthedocs.org/
where to host
additional
documentation?
https://pages.github.com/
Interactive
Documentation
https://swagger.io/
https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v3.0
https://developer.webex.com/docs/platform-introduction
https://news.codecademy.com/content/images/2018/08/Screen-Shot-2018-08-22-at-1.49.22-
PM.png
https://maintainer.io/
More to follow?
Learn more about the new DevNet Certifications
and how you can prepare now!
Associate Level Specialist Level Professional Level Expert Level
Engineering
Future
Offering
Software
Start Here | Upcoming Cisco DevNet Certifications
• Start at Meet DevNet
DEVNET-2864: Getting ready for Cisco DevNet Certifications
Offered daily at 9am, 1pm & 4pm at Meet DevNet
• Attend a brownbag session

DEVNET-4099: DevNet Certifications: Bringing software practices & software skills
to networking
Offered daily 12:15-12:45 in the DevNet Zone Theater
• Visit the Learning@Cisco booth

• Scan this code to sign up for the latest updates or go to
http://cs.co/20eur02
Find shared code repositories of
use cases for network automation & more! Don’t miss our 5
Automate Infrastructure
demos in the
DevNet Zone!
Scan this code or go to

the URL to learn more
Start at Meet DevNet

DEVNET-3010 [a-j] Learn how to make Network Automation Simple
with the Community
Offered Monday 2pm & 5pm, Tuesday & Wednesday 10am, 2pm & 5pm, http://cs.co/20eur01
and Thursday 10am & 5pm at Meet DevNet
Complete your
online session
survey • Please complete your session survey
after each session. Your feedback
is very important.
• Complete a minimum of 4 session
surveys and the Overall Conference
survey (starting on Thursday) to
receive your Cisco Live t-shirt.
• All surveys can be taken in the Cisco Events
Mobile App or by logging in to the Content
Catalog on ciscolive.com/emea.
Cisco Live sessions will be available for viewing on

demand after the event at ciscolive.com.
Continue your education
Demos in the
Walk-In Labs
Cisco Showcase
Meet the Engineer

Related sessions
1:1 meetings
Thank you

Devnet 1069

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Devnet 1069

Uploaded by

Copyright:

Available Formats

Oh you've built the best product in

the world? Come back when you

things to point out tools

linting flag programming errors, bugs,

"First line in file should be a top level

a few extra tips on Editing vs Copy/Paste – Make it

Expected Output – It's always

Which information resources do you use (a) to get started or (b) to

• Grants rights for

Software Creative {roprietary Private,

GNU GPLv3 (Copyleft)

Apache License 2.0 (Permissive)

environments jupyter notebooks

1. Draw two circles 2. Draw the rest of the owl

Design, Build, Design, Build, Design, Build,

promote your effort questions on StackOverflow and

• Attend a brownbag session

• Visit the Learning@Cisco booth

Scan this code or go to

Start at Meet DevNet

Cisco Live sessions will be available for viewing on

Meet the Engineer

You might also like