The Emperor Has No Docs (Geecon Oct'23)

@ignasi35 https://en.wikipedia.org/wiki/The_Triplets

@ignasi35
Google images: Les tres bessones

@ignasi35
1. The Boring Witch is bored and checks up on the triplets
2. The triplets just messed something up
3. The Boring Witch casts the triplets away into a story or novel
4. The story is twisted or the triplets interfere with it
5. The Boring Witch jumps in to teach a lesson to the triplets
6. The triplets sort everything out
7. The Boring Witch brings the triplets back

@ignasi35
The plots of the triplet sisters follow a de
fi
nite pattern. Sometimes they
play some prank or manage to annoy the Bored Witch, and, to punish
them, she sends them into a classic tale, legend, or children's or
adult's (such as Frankenstein or The Phantom of the Opera) literary
work. The main structure of the classic remains, but some twists (often
hilarious anachronisms such as showing The forty thieves getting
distracted from robbing a house by a camel race on TV or Dr.
Frankenstein as a veterinarian) are introduced to favor each plot and
de
fi
ne the sisters' personalities.
https://en.wikipedia.org/wiki/The_Triplets

@ignasi35
The plots of the triplet sisters follow a de
fi
nite pattern. Sometimes they
play some prank or manage to annoy the Bored Witch, and, to punish
them, she sends them into a classic tale, legend, or children's or
adult's (such as Frankenstein or The Phantom of the Opera) literary
work. The main structure of the classic remains, but some twists (often
hilarious anachronisms such as showing The forty thieves getting
distracted from robbing a house by a camel race on TV or Dr.
Frankenstein as a veterinarian) are introduced to favor each plot and
de
fi
ne the sisters' personalities.
,
. As a punishment,
https://en.wikipedia.org/wiki/The_Triplets

@ignasi35
• focused on the plot structure
• explained examples in a follow-up paragraph
• kept sentences shorter and simpler
I would have

@ignasi35
• put production code in src/main/
• put test code in src/tests/
• used small functions and composed them
I would have

@ignasi35
• use ordered lists when order matters - <ol><li/></ol>
• use unordered lists if order won't matter - <ul><li/></ul>
META

@ignasi35
• use imperative
META META

@ignasi35
1. The Boring Witch is bored and check up on the triplets
2. The triplets just messed something up
3. The Boring Witch casts the triplets away into a kids story
4. The story is twisted or the triplets interfere with it
5. The Boring Witch jumps in to teach a lesson to the triplets
6. The triplets sort everything out
7. The Boring Witch brings the triplets back

@ignasi35
• prefer direct form over passive form
• use passive form only if the subject is unknown (and, even then,
reconsider using passive form)
META

@ignasi35
• state your audience
• manage expectations
• <content>
• review expectations
• close with links to follow-up contents
META

@ignasi35
• <content>
META
Who am I ?

@ignasi35
The Emperor Has No Docs
Ignasi Marimon-Clos i Sunyol
GeeCon - Oct'23 - Prague

http://qa.geecon.cz
http://sli.do #geecon
Room 6

@ignasi35
Who am I
developer
developer
developer

@ignasi35
!(Who am I)
Graphics designer

@ignasi35
Goals promised
journey: from no docs to documenting
tips and tricks
habits to not forget docs
cases and audience where docs can save money
counter usual arguments against writing docs

@ignasi35
read specs
code
test
doc

@ignasi35
skim specs
code
deploy
read spec
code again
test
doc

@ignasi35
Source: IMDB
skim specs
code
deploy
read spec
code again
test
doc

@ignasi35
read specs
ask for clari
fi
cation
collaborate over writing tests
code
doc

@ignasi35
Personal kicks
do docs and only docs for days or even weeks
OSS personal experience

@ignasi35
Personal kicks
learn, learn, learn
4C model
4C's of effective docs
the Divio Doc System

@ignasi35
4
C model
Context
Container
Component
Code

@ignasi35
4
C model
Context - an OTA with 4 BU's
Container
Component
Code

@ignasi35
4
C model
Context - an OnlineTravelAgency with 4 BizzUnits
Container
Component
Code

@ignasi35
4
C model
Context - an OnlineTravelAgency with 4 BizzUnits
Container - bookings, recommendations, currency exchange,...
Component - booking requires X, Y, Z steps; persistence,...
Code - internal details on the currency exchange service

@ignasi35
4
C's of effective docs
Clear
Concise
Correct
Complete

@ignasi35
4
C's of effective docs
Clear
Concise
Correct
Complete
Similar properties
than code

@ignasi35
The Divio System
https://documentation.divio.com/

@ignasi35
Personal kicks
BONUS
https://developers.google.com/tech-writing/overview

@ignasi35
tricks
fi
ght the Blank Page Syndrome
remove barriers impending micro-improvements
an improvement is cheaper than a creation

@ignasi35
tricks
create the explicit task of documenting
and start that task
fi
rst

@ignasi35
tricks
deliberate practice
breakfast - a micro PR every morning
katas

@ignasi35
Docs are tests I
don't compile

@ignasi35
"Docs are tests"
Complete, Clear, Concise,...
Different levels (Container, Code, Component,...)
Do them
fi
rst

@ignasi35
"Docs are tests"
Do them
fi
rst - Bonus
Prevent the Expert Paradox
Develop an Ubiquitous Language

@ignasi35
"Docs are tests"
Test Coverage
no coverage is bad
100% coverage is bad
Docs are like salt
de
fi
nitely not none
de
fi
nitely not too much

@ignasi35
"Docs are tests"
Test --> QA Docs --> Tech Writer

@ignasi35
"Docs are tests"
Outside-In
high level docs and diagrams (aka Integration Test)
Context, Container, Component
detail as you dig (aka Unit Test)
Code
be mindful of the user (ignore impl, focus on API)

@ignasi35
"be mindful of the user"
Documenting is a show of empathy and respect

@ignasi35
real life conversation
call
messaging
e-mail
docs

@ignasi35
Write once, read anytime

@ignasi35
PR reviewer is you earliest, closest reader

@ignasi35
tricks
Do them
fi
rst
Prevent the Expert Paradox
Develop an Ubiquitous Language - Naming!
Add visuals to help yourself and other reviewers
Link to docs from the PRs for extra context
Detect unknown unknowns faster

@ignasi35
"Once the task is
9
0
% done,
you only need to write the code"

@ignasi35
tricks
Docs are not Specs

@ignasi35
habits
Build your list of triggers

@ignasi35
triggers
"When coding, I shouldn't need to select names."
"Build time is docs time"
"Describe PRs with a link to docs"
"suggestion beats comment"

https://twitter.com/depthsofwiki/status/
1
6
9
2
1
0
6
5
2
7
2
9
6
1
0
6
6
4
1

@ignasi35
triggers
On a blank page...
...focus on "why?"
Beat the Blank Page Syndrome!

@ignasi35
triggers
On a blank page...
... use AI to get up to speed fast.
Beat the Blank Page Syndrome!
Separate IDEs: one without AI, another with AI

@ignasi35
triggers

@ignasi35
triggers
PR submission process
push code
describe PR
create PR as DRAFT
comment the relevant areas of my own PR
mark the PR as Ready For Review

@ignasi35
triggers
Reinforce others
"Thank other when they add docs"

@ignasi35
triggers
"No acronyms"
"No ENTER without reading
fi
rst"

@ignasi35
fi
rst"
Write
Read
Reduce
Repeat

@ignasi35
fi
rst"
Reduce
Shorter sentences
No adverbs
No coupling to implementation details (if possible)

@ignasi35
"Use shorter
sentences"
Yes but:
https://www.helpscout.com/blog/damn-hard-writing/

@ignasi35
Save Money/Time
Onboarding content (tools and processes)
Get up to speed faster

@ignasi35
Save Money
Onboarding
Enforce writing training
Promote a strong writing culture (*)
(*) https://twitter.com/gimenete/status/
1
7
0
8
9
3
1
9
1
7
9
3
0
7
7
4
8
3
1
https://twitter.com/erikras/status/
1
7
0
8
9
3
2
6
4
8
1
7
1
7
0
8
5
9
4

@ignasi35
Save Money/Time
Onboarding initial tasks: read and improve docs
learn the product
familiarise with the docs structure and location

@ignasi35
Save Money/Time
Docs on internal tooling and processes everyone must use
Anything I can't Google
SOPs, deployment processes, ...

@ignasi35
Save Money/Time
Docs on internal tooling and processes everyone must use
Anything I can't Google
Standard Operating Procedures, deployment processes, ...

@ignasi35
Save Money/Time
Discoverability and Announcing

@ignasi35
Save Money/Time
Convention
All docs of type X are in location Y
README.md
docs/
Roadie
Con
fl
uence
Target Audience?

@ignasi35
Save Money
Make content discoverable
How-To's MUST be named "📚How-To: X"
Manuals MUST be named "📚Manual: Y"

@ignasi35
Save Money
links links and links

@ignasi35
Save Money
Document in-place
DRY?
WET!

@ignasi35
Save Money
convention < discoverability < links < in-place docs

@ignasi35
"Documentation is
hard to maintain"
"Undocumented
code is harder to
maintain"

@ignasi35
"I don't know what
to explain. Or in
how much detail."
"Focus on the WHY.
Some docs is better
than no docs.
Document as you
code. Put yourself
on the user's shoes:
empathy!"

@ignasi35
"This code is very
stable, no one
edits it"
"But people uses
it. Other services
its data. Users
need to know how
it behaves"

@ignasi35
"I don't know
where to store the
docs"
"Write the docs,
we'll publish them
in the right place
later"

@ignasi35
"It takes time"
"Heh! You know,
see, it's funny,
because I have a
full slide-deck
about that."

@ignasi35
"I answered this
on slack, just
search there"
"Oh, I took your
answer from Slack
and moved it to
the Wiki in the
time it took you to
answer.

@ignasi35
"I'm the Team
Lead, ask me
anything"
"Here's a question
for you:
ever heard of the
Bus Factor?"

@ignasi35
"MY CODE IS THE
DOCUMENTATION"
"THE TYPES ARE
THE
DOCUMENTATION"
"String.split"
"BigDecimal's scale"

@ignasi35
java.math.BigDecimal

@ignasi35
12345678 * 10^-2 = 123456.78
12345678 * 10^2 = 1234567800

@ignasi35
• <content> ---> Goals Promised
META

@ignasi35
Goals promised
1. journey: from no docs to documenting
2. tips and tricks
3. habits to not forget docs
4. cases and audience where docs can save money
5. counter usual arguments against writing docs

@ignasi35
Goals promised
1. journey: from no docs to documenting - evolve self
2. tips and tricks

@ignasi35
Goals promised
2. tips and tricks - detect what works, hack yourself

@ignasi35
Goals promised
3. habits to not forget docs - build habits to not fall back

@ignasi35
Goals promised
4. cases and audience where docs can save money - stakeholders

@ignasi35
Goals promised
4. cases and audience where docs can save money - stakeholders
5. counter usual arguments against writing docs - rally the troops

@ignasi35
Goals promised
1. kicks
2. tricks
3. triggers
4. moneyz
5. troops

@ignasi35
References and Thanks
All images (except explicitly stated): OpenAI Dall-E 2
Dragon challenges: Slack BcnEng
The Triplets: Roser Capdevila & Mercè Company

@ignasi35
The Emperor Has No Docs
Ignasi Marimon-Clos i Sunyol
GeeCon - Oct'23 - Prague
Is A Superhero

@ignasi35
https://service.mattel.com/instruction_sheets/UNO%
2
0
Basic%
2
0
IS.pdf

The Emperor Has No Docs (Geecon Oct'23)

Recommended

Recommended

More Related Content

Similar to The Emperor Has No Docs (Geecon Oct'23)

Similar to The Emperor Has No Docs (Geecon Oct'23) (20)

More from Ignasi Marimon-Clos i Sunyol

More from Ignasi Marimon-Clos i Sunyol (10)

Recently uploaded

Recently uploaded (20)

The Emperor Has No Docs (Geecon Oct'23)