Humanizing Your Documentation bit.ly/docs-talk-resources - - PowerPoint PPT Presentation

▶
humanizing your documentation
SMART_READER_LITE
LIVE PREVIEW

Humanizing Your Documentation bit.ly/docs-talk-resources - - PowerPoint PPT Presentation

Feb 09, 2024 113 likes •969 views

Humanizing Your Documentation bit.ly/docs-talk-resources @carolstran Why do we write documentation? Tyner Blain - bit.ly/goal-drive-docs Use case driven documentation Tyner Blain - bit.ly/use-case-docs Tyner Blain - bit.ly/goal-drive-docs

slide-1
SLIDE 1

Humanizing Your Documentation

@carolstran

bit.ly/docs-talk-resources

slide-2
SLIDE 2

Why do we write documentation?

Tyner Blain - bit.ly/goal-drive-docs

slide-3
SLIDE 3

Use case driven documentation

Tyner Blain - bit.ly/use-case-docs

slide-4
SLIDE 4

Tyner Blain - bit.ly/goal-drive-docs

slide-5
SLIDE 5

How to adjust the speed How to change the direction How to change the drill bit

Tyner Blain - bit.ly/goal-drive-docs

slide-6
SLIDE 6

How to drill a hole in a flat surface How to select the right screw How to stir paint with your drill

Tyner Blain - bit.ly/goal-drive-docs

slide-7
SLIDE 7

Who do we write documentation for?

@carolstran

slide-8
SLIDE 8

Humans

@carolstran

slide-9
SLIDE 9

@carolstran

slide-10
SLIDE 10

Slack API Portal - bit.ly/slack-docs

slide-11
SLIDE 11

Slack API Portal - bit.ly/slack-docs

Making messages interactive Subscribing to Event Types Events API vs. RTM API

slide-12
SLIDE 12

Slack API Portal - bit.ly/slack-docs

slide-13
SLIDE 13

Goal Use Case

Tyner Blain - bit.ly/use-case-docs

slide-14
SLIDE 14

Functional Requirement

Design Implementation

Tyner Blain - bit.ly/use-case-docs

Goal Use Case

slide-15
SLIDE 15

Functional Requirement

Design Implementation

Tyner Blain - bit.ly/use-case-docs

Goal Use Case

slide-16
SLIDE 16

Functional Requirement

Design Implementation

Tyner Blain - bit.ly/use-case-docs

Goal Use Case

slide-17
SLIDE 17

This is cool

@carolstran

slide-18
SLIDE 18

But it doesn’t happen

@carolstran

slide-19
SLIDE 19

JavaScript

@carolstran

slide-20
SLIDE 20

@carolstran

What’s going on? Why is this so confusing? Do people actually enjoy this?

slide-21
SLIDE 21

No one wants to read your docs

@carolstran

slide-22
SLIDE 22

No one wants to read your docs

@carolstran

slide-23
SLIDE 23

People don’t mind reading docs…

@carolstran

slide-24
SLIDE 24

…as long as they’re actually helpful

@carolstran

slide-25
SLIDE 25

Ethan McQuarrie - bit.ly/EthanMcQuarrie-tweet

slide-26
SLIDE 26

Killian McMahon - bit.ly/kilmc-tweet

slide-27
SLIDE 27

Leigh Momii - bit.ly/jetleigh-tweet

slide-28
SLIDE 28

Leigh Momii - bit.ly/jetleigh-tweet

slide-29
SLIDE 29

Leigh Momii - bit.ly/jetleigh-tweet

slide-30
SLIDE 30

If only developers cared about docs…

@carolstran

slide-31
SLIDE 31

If only developers cared about docs…

@carolstran

slide-32
SLIDE 32

Writing docs is only part of the job

@carolstran

slide-33
SLIDE 33

The words we choose

Lucie Le Naour - bit.ly/wtd-lucie

slide-34
SLIDE 34

Insensitive language

@carolstran

slide-35
SLIDE 35

If the programmer wishes to uphold the invariant, he must satisfy the function’s preconditions

slide-36
SLIDE 36

Problematic but common terms

@carolstran

slide-37
SLIDE 37

Master / Slave Whitelist / Blacklist

slide-38
SLIDE 38

Think before you type

@carolstran

slide-39
SLIDE 39

Primary / Replica Denylist / Allowlist

@carolstran

slide-40
SLIDE 40

bit.ly/alex-js

slide-41
SLIDE 41

bit.ly/alex-js

slide-42
SLIDE 42

Linters aren’t a replacement for human editing

@carolstran

slide-43
SLIDE 43

Tatiana Mac - selfdefined.app

slide-44
SLIDE 44

Saying ‘simply’ or ‘easy’

@carolstran

slide-45
SLIDE 45

Don’t say it

@carolstran

slide-46
SLIDE 46

Be specific

Jim Fisher - bit.ly/dont-say-simply

slide-47
SLIDE 47

Be comparative

Jim Fisher - bit.ly/dont-say-simply

slide-48
SLIDE 48

Be absolute

Jim Fisher - bit.ly/dont-say-simply

slide-49
SLIDE 49

Show, don’t tell

Jim Fisher - bit.ly/dont-say-simply

slide-50
SLIDE 50

bit.ly/write-good

slide-51
SLIDE 51

write-good *.md

write good - bit.ly/write-good

slide-52
SLIDE 52

Bloated language

@carolstran

slide-53
SLIDE 53

Plain language

@carolstran

slide-54
SLIDE 54

hemingwayapp.com

slide-55
SLIDE 55

“No one has ever complained that something was too easy to read”

Ashley Bischoff - bit.ly/ashley-fronteers

slide-56
SLIDE 56

Unexpected errors

@carolstran

slide-57
SLIDE 57

Address common errors

@carolstran

slide-58
SLIDE 58

What might happen Potential reasons why What to do next

@carolstran

slide-59
SLIDE 59

Apple Computer Inc - bit.ly/appleII-manual

slide-60
SLIDE 60

Django Girls - bit.ly/django-girls-tut

slide-61
SLIDE 61

You’re in too deep

@carolstran

slide-62
SLIDE 62

Everyone is a beginner at some point

@carolstran

slide-63
SLIDE 63

Take a step back

@carolstran

slide-64
SLIDE 64

The code we write

@carolstran

slide-65
SLIDE 65

Code snippets shouldn’t be screenshots

@carolstran

slide-66
SLIDE 66

<code> for inline

MDN <code> docs - bit.ly/mdn-code

slide-67
SLIDE 67

<pre> for blocks

MDN <pre> docs - bit.ly/mdn-pre

slide-68
SLIDE 68

```javascript

Markdown Cheatsheet - bit.ly/md-cheatsheet

slide-69
SLIDE 69

Foo / Bar / Baz

@carolstran

slide-70
SLIDE 70

Meaningful placeholders

@carolstran

slide-71
SLIDE 71

“We can have variable names that are both meaningful and generic that expose their purpose via their semantics”

Eli Schütze Ramirez - bit.ly/elibelly-reply

slide-72
SLIDE 72

var baz = [‘foo’, ‘bar’]

slide-73
SLIDE 73

var fruits = [‘apple’, ‘banana']

MDN JS array docs - bit.ly/js-array-mdn

slide-74
SLIDE 74

var array_name = [‘item1’, ‘item2’]

slide-75
SLIDE 75

The structure of our documentation

@carolstran

slide-76
SLIDE 76

Poorly defined structure

@carolstran

slide-77
SLIDE 77

Mindful structure

@carolstran

slide-78
SLIDE 78

Explain the feature Describe the use case(s) Recommend tooling

@carolstran

slide-79
SLIDE 79

Your product isn’t the right solution

@carolstran

slide-80
SLIDE 80

Be transparent

@carolstran

slide-81
SLIDE 81

bit.ly/reasonml-docs

slide-82
SLIDE 82

Final note

@carolstran

slide-83
SLIDE 83

Accuracy and consistency

@carolstran

slide-84
SLIDE 84

Aim to be honest, helpful and human

@carolstran

slide-85
SLIDE 85

@carolstran

bit.ly/docs-talk-resources