The art of documentation and

133
The Art Of Documentation and Readme.md @Ben_Hall [email protected] Katacoda.com

Transcript of The art of documentation and

Page 1: The art of documentation and

The Art Of Documentation

and Readme.md

@Ben_Hall

[email protected]

Katacoda.com

Page 2: The art of documentation and
Page 3: The art of documentation and
Page 4: The art of documentation and

The Art Of Documentation

and Readme.md

@Ben_Hall

[email protected]

Katacoda.com

Page 5: The art of documentation and

@Ben_Hall / Blog.BenHall.me.uk

WH

O A

M I?

Page 6: The art of documentation and

Learn via Interactive Browser-Based LabsKatacoda.com

Page 7: The art of documentation and

Agenda

• User's Product Journey

• How User's Learn

• 5 Stages of Documentation

• How it applies to Readme.md

• Managing Docs

Page 8: The art of documentation and

How documentation can help the

adoption of your product/project

Different to code documentation

Page 9: The art of documentation and

Where to begin?

Page 10: The art of documentation and

The journey begins long before

mycompany.com/docs

Page 11: The art of documentation and

Not created once the product is

complete

Page 12: The art of documentation and

Users engage with your site, your

examples, your demos before

reading your documentation

Page 13: The art of documentation and
Page 14: The art of documentation and
Page 15: The art of documentation and
Page 16: The art of documentation and

Exploration Getting StartedOnBoarding/Problem

SolvingGuidance/Discovery Reference

Page 17: The art of documentation and

Exploration Getting StartedOnBoarding/Problem

SolvingGuidance/Discovery Reference

One Minute

9 Minutes

Page 18: The art of documentation and

Website and Readme.md

Page 19: The art of documentation and
Page 20: The art of documentation and
Page 21: The art of documentation and
Page 22: The art of documentation and

“Call Us”

Page 23: The art of documentation and

OnBoarding/Problem Solving Guidance/Discovery Reference

Page 24: The art of documentation and

Maps to how users learn

Page 25: The art of documentation and
Page 26: The art of documentation and
Page 27: The art of documentation and
Page 28: The art of documentation and
Page 29: The art of documentation and
Page 30: The art of documentation and
Page 31: The art of documentation and

Exploration Getting StartedOnBoarding/Problem

SolvingGuidance/Discovery Reference

How to start creating

documentation

Page 32: The art of documentation and

Stage 1: Exploration

Page 33: The art of documentation and

This is your first piece of

documentation

Page 34: The art of documentation and

“Why should I care?”

Page 35: The art of documentation and
Page 36: The art of documentation and
Page 37: The art of documentation and
Page 38: The art of documentation and
Page 39: The art of documentation and
Page 40: The art of documentation and
Page 41: The art of documentation and
Page 42: The art of documentation and
Page 43: The art of documentation and
Page 44: The art of documentation and

Stage 2: Getting Started

Page 45: The art of documentation and

9 minutes left for users to identify

value

Page 46: The art of documentation and

“Do you solve my problem?”

Page 47: The art of documentation and

Can your product relate to my

dream/problem?

Page 48: The art of documentation and
Page 49: The art of documentation and
Page 50: The art of documentation and
Page 51: The art of documentation and
Page 52: The art of documentation and
Page 53: The art of documentation and
Page 54: The art of documentation and
Page 55: The art of documentation and

What about mobile/iPad?

🤔

Page 56: The art of documentation and
Page 57: The art of documentation and
Page 58: The art of documentation and
Page 59: The art of documentation and
Page 60: The art of documentation and
Page 61: The art of documentation and

Source-only Releases

Page 62: The art of documentation and

Broken Samples

Page 63: The art of documentation and

Video Content

Page 64: The art of documentation and
Page 65: The art of documentation and
Page 66: The art of documentation and

Stage 3: Onboarding

Page 67: The art of documentation and

“Congratulations! I want to use

your product”

Page 68: The art of documentation and

How quickly can you get them

started?

Page 69: The art of documentation and

Provision API keys, access

tokens, downloads

Page 70: The art of documentation and
Page 71: The art of documentation and
Page 72: The art of documentation and
Page 73: The art of documentation and
Page 74: The art of documentation and
Page 75: The art of documentation and

Stage 4: Guidance and

Discovery

Page 76: The art of documentation and

“Your product is solving my

problem. What other problems

can you solve?”

Page 77: The art of documentation and
Page 78: The art of documentation and
Page 79: The art of documentation and
Page 80: The art of documentation and
Page 81: The art of documentation and
Page 82: The art of documentation and
Page 83: The art of documentation and
Page 84: The art of documentation and
Page 85: The art of documentation and
Page 86: The art of documentation and
Page 87: The art of documentation and
Page 88: The art of documentation and

Promote Your Community

Page 89: The art of documentation and
Page 90: The art of documentation and
Page 91: The art of documentation and

Stage 5: Reference

Page 92: The art of documentation and

Becoming an expert…

Page 93: The art of documentation and
Page 94: The art of documentation and
Page 95: The art of documentation and

But what about Readme.md?

Page 96: The art of documentation and

Exploration Getting StartedOnBoarding/Problem

SolvingGuidance/Discovery Reference

Page 97: The art of documentation and
Page 98: The art of documentation and

Sets the tone

Page 99: The art of documentation and
Page 100: The art of documentation and

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

Page 101: The art of documentation and
Page 102: The art of documentation and
Page 103: The art of documentation and
Page 104: The art of documentation and
Page 105: The art of documentation and

Building community

Page 106: The art of documentation and

Open Source Focused

• Include Contributors guidelines

• Include License

• Include where to discuss the project

Page 107: The art of documentation and

“Just Read The Tests”

Page 108: The art of documentation and

Managing Docs

Page 109: The art of documentation and

Separate Project

Page 110: The art of documentation and
Page 111: The art of documentation and
Page 112: The art of documentation and
Page 113: The art of documentation and

Build it’s own community

Page 114: The art of documentation and

Kubernetes sig-docs

Page 115: The art of documentation and
Page 116: The art of documentation and
Page 117: The art of documentation and

Automated tests for your

examples?

Page 118: The art of documentation and

Make it easy to provide feedback

Page 119: The art of documentation and
Page 120: The art of documentation and
Page 121: The art of documentation and
Page 122: The art of documentation and
Page 123: The art of documentation and

Who creates the “best”

documentation?

Page 124: The art of documentation and
Page 125: The art of documentation and
Page 126: The art of documentation and
Page 127: The art of documentation and
Page 128: The art of documentation and
Page 129: The art of documentation and
Page 130: The art of documentation and

https://betta.io/blog/2016/12/14/what-developer-experience-could-learn-from-lego/

Page 131: The art of documentation and

Exploration Getting StartedOnBoarding/Problem

SolvingGuidance/Discovery Reference

Page 132: The art of documentation and

www.katacoda.comblog.BenHall.me.uk

Page 133: The art of documentation and

Thank you!@Ben_Hall

[email protected]

www.Katacoda.com