SlideShare a Scribd company logo
The Art Of Documentation
and Readme.md
@Ben_Hall
Ben@BenHall.me.uk
Katacoda.com
The art of documentation and readme.md
The art of documentation and readme.md
The Art Of Documentation
and Readme.md
@Ben_Hall
Ben@BenHall.me.uk
Katacoda.com
@Ben_Hall / Blog.BenHall.me.uk
WHOAMI?
Learn via Interactive Browser-Based Labs
Katacoda.com
Agenda
• User's Product Journey
• How User's Learn
• 5 Stages of Documentation
• How it applies to Readme.md
• Managing Docs
How documentation can help the
adoption of your product/project
Different to code documentation
Where to begin?
The journey begins long before
mycompany.com/docs
Not created once the product is
complete
Users engage with your site, your
examples, your demos before
reading your documentation
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Exploration Getting Started
OnBoarding/Problem
Solving
Guidance/Discovery Reference
Exploration Getting Started
OnBoarding/Problem
Solving
Guidance/Discovery Reference
One Minute
9 Minutes
Website and Readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
“Call Us”
OnBoarding/Problem Solving Guidance/Discovery Reference
Maps to how users learn
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Exploration Getting Started
OnBoarding/Problem
Solving
Guidance/Discovery Reference
How to start creating
documentation
Stage 1: Exploration
This is your first piece of
documentation
“Why should I care?”
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Stage 2: Getting Started
9 minutes left for users to identify
value
“Do you solve my problem?”
Can your product relate to my
dream/problem?
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
What about mobile/iPad?
🤔
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Source-only Releases
Broken Samples
Video Content
The art of documentation and readme.md
The art of documentation and readme.md
Stage 3: Onboarding
“Congratulations! I want to use
your product”
How quickly can you get them
started?
Provision API keys, access
tokens, downloads
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Stage 4: Guidance and
Discovery
“Your product is solving my
problem. What other problems
can you solve?”
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Promote Your Community
The art of documentation and readme.md
The art of documentation and readme.md
Stage 5: Reference
Becoming an expert…
The art of documentation and readme.md
The art of documentation and readme.md
But what about Readme.md?
Exploration Getting Started
OnBoarding/Problem
Solving
Guidance/Discovery Reference
The art of documentation and readme.md
Sets the tone
The art of documentation and readme.md
What should be included?
• Why project exists
• Show them what problems it solves
• Show them how to get started
• Tell them how to be successful
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Building community
Open Source Focused
• Include Contributors guidelines
• Include License
• Include where to discuss the project
“Just Read The Tests”
Managing Docs
Separate Project
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Build it’s own community
Kubernetes sig-docs
The art of documentation and readme.md
The art of documentation and readme.md
Automated tests for your
examples?
Make it easy to provide feedback
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
Who creates the “best”
documentation?
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
The art of documentation and readme.md
https://betta.io/blog/2016/12/14/what-developer-experience-could-learn-from-lego/
Exploration Getting Started
OnBoarding/Problem
Solving
Guidance/Discovery Reference
www.katacoda.com
blog.BenHall.me.uk
Thank you!
@Ben_Hall
Ben@BenHall.me.uk
www.Katacoda.com

More Related Content

What's hot (17)

PPTX
Dropbox presentation
Craig Hammond
 
PPTX
Anupi web tools to empower language learners mazatlan 2014
Cynthia Wiseman
 
KEY
Apps and tools
Byron Mitchell
 
PPTX
EIS Smackdown 2012
grhartman
 
PPT
Pete Fraser - Top Tips (2)
anouska1234
 
PPT
Webquests
Cándida Gallardo
 
PDF
At2012 bengaluru continuous_visibility-souvikb
India Scrum Enthusiasts Community
 
PDF
Intro to Yo
Shawn Rider
 
PPT
Lessons From Lib Guides
Laura Harris
 
PPTX
Simple online portfolios using google sites
samquell
 
PDF
Introduction to Confluence Blueprints
Matthew Cobby
 
PDF
Working With Web Standards
dylanbathurst
 
PPT
What Is A Blog?
Web Success Coaching
 
KEY
Inclusive design: real accessibility for everyone
Chris Mills
 
KEY
Web education, and the Opera web standards curriculum
Chris Mills
 
PPT
Lecture 9 Usability Orignal
Sur College of Applied Sciences
 
PDF
Ux testing recap
Angela Byron
 
Dropbox presentation
Craig Hammond
 
Anupi web tools to empower language learners mazatlan 2014
Cynthia Wiseman
 
Apps and tools
Byron Mitchell
 
EIS Smackdown 2012
grhartman
 
Pete Fraser - Top Tips (2)
anouska1234
 
At2012 bengaluru continuous_visibility-souvikb
India Scrum Enthusiasts Community
 
Intro to Yo
Shawn Rider
 
Lessons From Lib Guides
Laura Harris
 
Simple online portfolios using google sites
samquell
 
Introduction to Confluence Blueprints
Matthew Cobby
 
Working With Web Standards
dylanbathurst
 
What Is A Blog?
Web Success Coaching
 
Inclusive design: real accessibility for everyone
Chris Mills
 
Web education, and the Opera web standards curriculum
Chris Mills
 
Lecture 9 Usability Orignal
Sur College of Applied Sciences
 
Ux testing recap
Angela Byron
 

Similar to The art of documentation and readme.md (20)

PPTX
The Art of Documentation and Readme.md for Open Source Projects
Ben Hall
 
PPTX
The Art Of Documentation for Open Source Projects
Ben Hall
 
PDF
NLJUG Speaker academy 2025 - first session
Bert Jan Schrijver
 
PDF
Getting Down and Dirty with Accessibility and Usability workshop at TCUK12
Karen Mardahl
 
PDF
UX in Action: IBM Watson
UserTesting
 
PDF
NLJUG speaker academy 2024 - session 1, June 2024
Bert Jan Schrijver
 
PDF
NLJUG speaker academy 2023 - session 1
Bert Jan Schrijver
 
PDF
NLJUG speaker academy 2022 - session 1
Bert Jan Schrijver
 
PPT
Prototyping - the what, why and how at the University of Edinburgh
Neil Allison
 
PPTX
Get real results from your website
Florizel Media
 
PPT
Collaboration Beyond Code
David E. Weekly
 
PDF
COMP 4026 Lecture3 Prototyping and Evaluation
Mark Billinghurst
 
PPTX
Pedagogical Use of iPads
James Little
 
PPTX
DPC Web Archiving & Preservation Webinar #4: Outreach & Awareness Raising
Anna Perricci
 
PDF
Hindu college may 09 20
Sushumnarao Tadinada
 
PPT
Making and sharing content online
Helen Webster
 
PPT
From Project to Program: Building Sustainable Digital Collections
egore
 
PPTX
Getting Started With Omeka (DHSI 2015 Unconference)
jkmcgrath
 
PPTX
How to become a software developer
Eyob Lube
 
PPTX
User experience for drupal
Anne Stefanyk
 
The Art of Documentation and Readme.md for Open Source Projects
Ben Hall
 
The Art Of Documentation for Open Source Projects
Ben Hall
 
NLJUG Speaker academy 2025 - first session
Bert Jan Schrijver
 
Getting Down and Dirty with Accessibility and Usability workshop at TCUK12
Karen Mardahl
 
UX in Action: IBM Watson
UserTesting
 
NLJUG speaker academy 2024 - session 1, June 2024
Bert Jan Schrijver
 
NLJUG speaker academy 2023 - session 1
Bert Jan Schrijver
 
NLJUG speaker academy 2022 - session 1
Bert Jan Schrijver
 
Prototyping - the what, why and how at the University of Edinburgh
Neil Allison
 
Get real results from your website
Florizel Media
 
Collaboration Beyond Code
David E. Weekly
 
COMP 4026 Lecture3 Prototyping and Evaluation
Mark Billinghurst
 
Pedagogical Use of iPads
James Little
 
DPC Web Archiving & Preservation Webinar #4: Outreach & Awareness Raising
Anna Perricci
 
Hindu college may 09 20
Sushumnarao Tadinada
 
Making and sharing content online
Helen Webster
 
From Project to Program: Building Sustainable Digital Collections
egore
 
Getting Started With Omeka (DHSI 2015 Unconference)
jkmcgrath
 
How to become a software developer
Eyob Lube
 
User experience for drupal
Anne Stefanyk
 
Ad

More from Ben Hall (20)

PPTX
The Art Of Documentation - NDC Porto 2022
Ben Hall
 
PPTX
Three Years of Lessons Running Potentially Malicious Code Inside Containers
Ben Hall
 
PPTX
Containers without docker
Ben Hall
 
PPTX
Deploying windows containers with kubernetes
Ben Hall
 
PPTX
How Secure Are Docker Containers?
Ben Hall
 
PPTX
The Challenges of Becoming Cloud Native
Ben Hall
 
PPTX
Scaling Docker Containers using Kubernetes and Azure Container Service
Ben Hall
 
PPTX
Experimenting and Learning Kubernetes and Tensorflow
Ben Hall
 
PPTX
Running .NET on Docker
Ben Hall
 
PPTX
Real World Lessons on the Pain Points of Node.JS Application
Ben Hall
 
PPTX
Tips on solving E_TOO_MANY_THINGS_TO_LEARN with Kubernetes
Ben Hall
 
PPTX
Deploying applications to Windows Server 2016 and Windows Containers
Ben Hall
 
PPTX
The How and Why of Windows containers
Ben Hall
 
PPTX
Lessons from running potentially malicious code inside containers
Ben Hall
 
PPTX
Deploying Windows Containers on Windows Server 2016
Ben Hall
 
PPTX
Learning Patterns for the Overworked Developer
Ben Hall
 
PPTX
Real World Lessons on the Pain Points of Node.js Applications
Ben Hall
 
PPTX
Implementing Google's Material Design Guidelines
Ben Hall
 
PPTX
Real World Experience of Running Docker in Development and Production
Ben Hall
 
PPTX
Lessons from running potentially malicious code inside Docker containers
Ben Hall
 
The Art Of Documentation - NDC Porto 2022
Ben Hall
 
Three Years of Lessons Running Potentially Malicious Code Inside Containers
Ben Hall
 
Containers without docker
Ben Hall
 
Deploying windows containers with kubernetes
Ben Hall
 
How Secure Are Docker Containers?
Ben Hall
 
The Challenges of Becoming Cloud Native
Ben Hall
 
Scaling Docker Containers using Kubernetes and Azure Container Service
Ben Hall
 
Experimenting and Learning Kubernetes and Tensorflow
Ben Hall
 
Running .NET on Docker
Ben Hall
 
Real World Lessons on the Pain Points of Node.JS Application
Ben Hall
 
Tips on solving E_TOO_MANY_THINGS_TO_LEARN with Kubernetes
Ben Hall
 
Deploying applications to Windows Server 2016 and Windows Containers
Ben Hall
 
The How and Why of Windows containers
Ben Hall
 
Lessons from running potentially malicious code inside containers
Ben Hall
 
Deploying Windows Containers on Windows Server 2016
Ben Hall
 
Learning Patterns for the Overworked Developer
Ben Hall
 
Real World Lessons on the Pain Points of Node.js Applications
Ben Hall
 
Implementing Google's Material Design Guidelines
Ben Hall
 
Real World Experience of Running Docker in Development and Production
Ben Hall
 
Lessons from running potentially malicious code inside Docker containers
Ben Hall
 
Ad

Recently uploaded (20)

PPTX
WooCommerce Workshop: Bring Your Laptop
Laura Hartwig
 
PDF
Reverse Engineering of Security Products: Developing an Advanced Microsoft De...
nwbxhhcyjv
 
PDF
How Startups Are Growing Faster with App Developers in Australia.pdf
India App Developer
 
PPTX
UiPath Academic Alliance Educator Panels: Session 2 - Business Analyst Content
DianaGray10
 
PDF
Complete JavaScript Notes: From Basics to Advanced Concepts.pdf
haydendavispro
 
PPTX
✨Unleashing Collaboration: Salesforce Channels & Community Power in Patna!✨
SanjeetMishra29
 
PPTX
Top iOS App Development Company in the USA for Innovative Apps
SynapseIndia
 
PDF
CIFDAQ Market Insights for July 7th 2025
CIFDAQ
 
PDF
CIFDAQ Weekly Market Wrap for 11th July 2025
CIFDAQ
 
PDF
NewMind AI - Journal 100 Insights After The 100th Issue
NewMind AI
 
PDF
Achieving Consistent and Reliable AI Code Generation - Medusa AI
medusaaico
 
PDF
Using FME to Develop Self-Service CAD Applications for a Major UK Police Force
Safe Software
 
PDF
DevBcn - Building 10x Organizations Using Modern Productivity Metrics
Justin Reock
 
PPT
Interview paper part 3, It is based on Interview Prep
SoumyadeepGhosh39
 
PDF
CIFDAQ Token Spotlight for 9th July 2025
CIFDAQ
 
PDF
Learn Computer Forensics, Second Edition
AnuraShantha7
 
PPTX
AUTOMATION AND ROBOTICS IN PHARMA INDUSTRY.pptx
sameeraaabegumm
 
PDF
Smart Trailers 2025 Update with History and Overview
Paul Menig
 
PDF
Blockchain Transactions Explained For Everyone
CIFDAQ
 
PDF
Smart Air Quality Monitoring with Serrax AQM190 LITE
SERRAX TECHNOLOGIES LLP
 
WooCommerce Workshop: Bring Your Laptop
Laura Hartwig
 
Reverse Engineering of Security Products: Developing an Advanced Microsoft De...
nwbxhhcyjv
 
How Startups Are Growing Faster with App Developers in Australia.pdf
India App Developer
 
UiPath Academic Alliance Educator Panels: Session 2 - Business Analyst Content
DianaGray10
 
Complete JavaScript Notes: From Basics to Advanced Concepts.pdf
haydendavispro
 
✨Unleashing Collaboration: Salesforce Channels & Community Power in Patna!✨
SanjeetMishra29
 
Top iOS App Development Company in the USA for Innovative Apps
SynapseIndia
 
CIFDAQ Market Insights for July 7th 2025
CIFDAQ
 
CIFDAQ Weekly Market Wrap for 11th July 2025
CIFDAQ
 
NewMind AI - Journal 100 Insights After The 100th Issue
NewMind AI
 
Achieving Consistent and Reliable AI Code Generation - Medusa AI
medusaaico
 
Using FME to Develop Self-Service CAD Applications for a Major UK Police Force
Safe Software
 
DevBcn - Building 10x Organizations Using Modern Productivity Metrics
Justin Reock
 
Interview paper part 3, It is based on Interview Prep
SoumyadeepGhosh39
 
CIFDAQ Token Spotlight for 9th July 2025
CIFDAQ
 
Learn Computer Forensics, Second Edition
AnuraShantha7
 
AUTOMATION AND ROBOTICS IN PHARMA INDUSTRY.pptx
sameeraaabegumm
 
Smart Trailers 2025 Update with History and Overview
Paul Menig
 
Blockchain Transactions Explained For Everyone
CIFDAQ
 
Smart Air Quality Monitoring with Serrax AQM190 LITE
SERRAX TECHNOLOGIES LLP
 

The art of documentation and readme.md

Editor's Notes

  • #12: Not created once the product is complete
  • #14: The art of documentation is making your docs feel part of your product
  • #15: Sadly most documentation is the Owl
  • #71: Trust