the art of documentation and for open source projects

The Art of Documentation

and Readme.md

for Open Source Projects

@Ben_Hall

Ben@BenHall.me.uk

Katacoda.com

The Art of Documentation

and Readme.md

for Open Source Projects

@Ben_Hall

Ben@BenHall.me.uk

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/

@Ben_Hall

Ben@BenHall.me.uk

Blog.BenHall.me.uk

www.Katacoda.com