the art of documentation and for open source projects
TRANSCRIPT
The Art of Documentation
and Readme.md
for Open Source Projects
@Ben_Hall
Katacoda.com
The Art of Documentation
and Readme.md
for Open Source Projects
@Ben_Hall
Katacoda.com
@Ben_Hall / Blog.BenHall.me.uk
WH
O A
M I?
Learn via Interactive Browser-Based LabsKatacoda.com
How documentation can transform
the adoption of your product/project
Different to code documentation
Where to begin?
https://twitter.com/samnewman/status/934185375291060224
https://twitter.com/joeerl/status/934473378601291776?s=09
The journey begins long before
myproduct.com/docs
Exploration Getting StartedOnBoarding/Problem
SolvingGuidance/Discovery Reference
Product Adoption JourneyApplies to both Website and Readme.md
Exploration Getting StartedOnBoarding/Problem
SolvingGuidance/Discovery Reference
Stage 1: Exploration
“Why should I care?”
Stage 2: Getting Started
“Do you really solve my
problem?”
“Download 10GB VM”
“Deploy using
CloudFormation”
Asking for a large commitment
before demonstrating you’re the
right fit
Do I have curl installed?
What about mobile/iPad?
🤔
Users understand what your
product does, and experienced
the dream!
Stage 3: Onboarding
“Congratulations! I want to use
your product”
The best documentation is the
one we don’t have to write.
People don’t read on the internet
“He thinks he’s people!” (Archer)
Show/Hide Headers Button
https://beta.developer.spotify.com/documentation/web-playback-sdk/quick-start/#initializing-the-sdk
Hard to document === missing
developer UX?
Build tooling to help?
Kubeadm
Why write documentation when
you can automate it?
https://www.katacoda.com/courses/kubernetes/getting-started-with-kubeadm
Stage 4: Guidance and
Discovery
“Your product is solving my
problem. What other problems
can you solve?”
Stage 5: Reference
Becoming an expert…
Exploration Getting StartedOnBoarding/Problem
SolvingGuidance/Discovery Reference
Clear Project DefinitionInteractive
Demos/ExamplesLow barriers to
get startedTutorials/Guides
Long Form Reference
But what about Readme.md?
Sets the tone
<details>
<summary><b>Examples</b></summary>
<ul>
<li>
<a href="./examples/json-body-parsing">Parse JSON</a></li>
<li>
<a href="./examples/urlencoded-body-parsing">Parse urlencoded form
(html `form` tag)</a></li>
</ul>
</details>
Build it’s own community
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/
