The art of documentation and
-
Upload
ben-hall -
Category
Technology
-
view
284 -
download
3
Transcript of The art of documentation and
@Ben_Hall / Blog.BenHall.me.uk
WH
O A
M I?
Learn via Interactive Browser-Based LabsKatacoda.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
Exploration Getting StartedOnBoarding/Problem
SolvingGuidance/Discovery Reference
Exploration Getting StartedOnBoarding/Problem
SolvingGuidance/Discovery Reference
One Minute
9 Minutes
Website and Readme.md
“Call Us”
OnBoarding/Problem Solving Guidance/Discovery Reference
Maps to how users learn
Exploration Getting StartedOnBoarding/Problem
SolvingGuidance/Discovery Reference
How to start creating
documentation
Stage 1: Exploration
This is your first piece of
documentation
“Why should I care?”
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?
What about mobile/iPad?
🤔
Source-only Releases
Broken Samples
Video Content
Stage 3: Onboarding
“Congratulations! I want to use
your product”
How quickly can you get them
started?
Provision API keys, access
tokens, downloads
Stage 4: Guidance and
Discovery
“Your product is solving my
problem. What other problems
can you solve?”
Promote Your Community
Stage 5: Reference
Becoming an expert…
But what about Readme.md?
Exploration Getting StartedOnBoarding/Problem
SolvingGuidance/Discovery Reference
Sets the tone
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
Building community
Open Source Focused
• Include Contributors guidelines
• Include License
• Include where to discuss the project
“Just Read The Tests”
Managing Docs
Separate Project
Build it’s own community
Kubernetes sig-docs
Automated tests for your
examples?
Make it easy to provide feedback
Who creates the “best”
documentation?
https://betta.io/blog/2016/12/14/what-developer-experience-could-learn-from-lego/
Exploration Getting StartedOnBoarding/Problem
SolvingGuidance/Discovery Reference
www.katacoda.comblog.BenHall.me.uk