A
ll
T
h
i
n
g
s
o
p
e
n
Good Code
Documents
itself and
other lies
Changing
Work
culture
through
documentation
Tania Allard, PhD
Developer Advocate @Microsoft
ixek / #AllThingsOpen DOI: 10.6084/m9.figshare.9989396
Slide 2
Slide 2 text
2
bit.ly/ato-docs-culture
Get the slides
@ixek bit.ly/ato-docs-culture
Slide 3
Slide 3 text
ABOUT ME
3
ABOUT ME
Open Source advocate
I complex systems
Machine learning / scientific computing
I am also a mechanical keyboards lover
@ixek bit.ly/ato-docs-culture
Slide 4
Slide 4 text
4
Takeaways
Documentation as the
entry point for paying
technical debt
Some useful tips to use
docs to drive change
What is technical debt?
Your takeaways
@ixek bit.ly/ato-docs-culture
Slide 5
Slide 5 text
who likes
writing
documentation?
5
@ixek bit.ly/ato-docs-culture
Slide 6
Slide 6 text
who actually writes
documentation as a regular
practice?
6
@ixek bit.ly/ato-docs-culture
Slide 7
Slide 7 text
7
What if you could change
your work culture…
writing documentation?
@ixek bit.ly/ato-docs-culture
Slide 8
Slide 8 text
8
and pay some technical debt?
@ixek bit.ly/ato-docs-culture
Slide 9
Slide 9 text
What is technical debt?
Slide 10
Slide 10 text
It’s like
the
monster
under
your bed
10
@ixek bit.ly/ato-docs-culture
Slide 11
Slide 11 text
Technical debt
A series of bad
decisions
11
WHAT I DO
Leading to error
prone code &
architecture
@ixek bit.ly/ato-docs-culture
Slide 12
Slide 12 text
Technical debt
A series of bad
decisions
12
WHAT I DO
Leading to using
resources
unnecessarily / with
no clear objective
@ixek bit.ly/ato-docs-culture
Slide 13
Slide 13 text
What
decisions
were made
in the past?
That prevent
me from
getting
stuff done
today
@ixek
Slide 14
Slide 14 text
What
causes
technical
debt?
14
@ixek bit.ly/ato-docs-culture
Slide 15
Slide 15 text
15
That project was due
yesterday!
I’ll come back and clean
tomorrow… or add the
docs tomorrow
Time
crunch
@ixek bit.ly/ato-docs-culture
19
Code Smells
Indicators of a deeper
problem (not bugs
necessarily)
Half-baked features
Commented out pieces
of code
No test / broken tests
Multiple versions of
CI/CD but only one in
use
No documentation or
poor documentation
@ixek bit.ly/ato-docs-culture
Slide 20
Slide 20 text
20
https://xkcd.com/2054/
House of cards effect - Infra smells
@ixek bit.ly/ato-docs-culture
Slide 21
Slide 21 text
21
https://xkcd.com/1794/
Everything is on FIRE - all the time
@ixek bit.ly/ato-docs-culture
Slide 22
Slide 22 text
22
Courtesy of Ashley Mcnamara
Everything is on FIRE - all the time
@ixek bit.ly/ato-docs-culture
Slide 23
Slide 23 text
23
Unstable or
underutilized
data
dependencies
@ixek bit.ly/ato-docs-culture
Slide 24
Slide 24 text
24
Pipeline
jungles
@ixek bit.ly/ato-docs-culture
Slide 25
Slide 25 text
Burning everything to
the ground
25
Refactor your code
base
Change your work culture ->
make everyone accountable
instead of pointing fingers
Which is easier to do?
@ixek bit.ly/ato-docs-culture
Slide 26
Slide 26 text
Burning everything to
the ground
26
Refactor your code
base
Change your work culture ->
make everyone accountable
instead of pointing fingers
Which is More impactful to do?
@ixek bit.ly/ato-docs-culture
Slide 27
Slide 27 text
27
Story
time
@ixek bit.ly/ato-docs-culture
Slide 28
Slide 28 text
28
You are
given a
present
● But you have to figure out how
to put it together
● With no instructions
@ixek bit.ly/ato-docs-culture
Slide 29
Slide 29 text
29
You are
given a
present
● Some pieces might be missing
so you will have to “build them
as you go”
● With minimal or no instructions
● Some pieces will never fit
● So you will need to build more
pieces
● Your present might never work -
as you’d expect it
@ixek bit.ly/ato-docs-culture
Slide 30
Slide 30 text
30
You are
given a
present
● You will be miserable all the
time
@ixek bit.ly/ato-docs-culture
Slide 31
Slide 31 text
Write the Docs!!
Make the Docs
valuable
31
Courtesy of Ashley Mcnamara
@ixek bit.ly/ato-docs-culture
Slide 32
Slide 32 text
Docs are part of the work - and the pipelines
32
https://github.com/nteract/papermill
No job is completed if there are no docs!!
@ixek bit.ly/ato-docs-culture
Slide 33
Slide 33 text
33
http://docs.astropy.org/en/stable/index.html#developer-documentation
Write as if your best friend is reading
@ixek bit.ly/ato-docs-culture
Slide 34
Slide 34 text
34
http://docs.astropy.org/en/stable/development/docguide.html
Confusing - get newcomers to contribute
Critical fixes have been found this way!
@ixek bit.ly/ato-docs-culture
Slide 35
Slide 35 text
Master / Slave
Blacklist / Whitelist
35
Problematic terms
Inclusive culture
not only in your
docs
Primary / Replica
Denylist / Allowlist
You’d be surprised on how a team can change
@ixek bit.ly/ato-docs-culture
Slide 36
Slide 36 text
36
https://alexjs.com/ VIsual Studio Code Extension https://cda.ms/146
@ixek bit.ly/ato-docs-culture
Slide 37
Slide 37 text
“Code tells you how, comments tell you why”
- Jeff Atwood
Comments describe your code to developers
37
https://github.com/pandas-dev/pandas/blob/18a9e4c8ab253e83ba43767d890576186be13332/pandas/core/dtypes/concat.py#L72
Commenting vs
documentation
@ixek
Slide 38
Slide 38 text
Docs describe its use and functionality to your users
Mindful structure:
- Explain the feature
- Describe the use cases
- Additional recommended tooling
- Common errors / gotchas
38
https://github.com/pandas-dev/pandas/blob/18a9e4c8ab253e83ba43767d890576186be13332/pandas/core/dtypes/concat.py#L72
Commenting vs
documentation
@ixek
Slide 39
Slide 39 text
If you
cannot
use the
mindful
structure
You might need to refactor
39
@ixek bit.ly/ato-docs-culture
Slide 40
Slide 40 text
The goal
of the
docs
Help your users / developers to
onboard and fast as possible
Make the right choice
Build trust
40
https://the-turing-way.netlify.com/introduction/introduction
@ixek bit.ly/ato-docs-culture
Slide 41
Slide 41 text
41
https://azure.microsoft.com/en-us/resources/samples/?sort=0
Give them useful starting points
@ixek bit.ly/ato-docs-culture
Slide 42
Slide 42 text
42
Make the abstract tangible
@ixek bit.ly/ato-docs-culture
Slide 43
Slide 43 text
43
Comic courtesy of Juliette Taka For the Open DreamKit project
Who and why is using your tools?
Abstractions, frameworks and use cases? -
does it make sense
@ixek bit.ly/ato-docs-culture
48
https://www.sphinx-doc.org/en/master/usage/quickstart.html
Bye bye manual docs
Because they are part of your pipelines
@ixek bit.ly/auto-docs-culture
Slide 49
Slide 49 text
● Schedule regular
timings
● Bring treats!
● Let them choose
● Review and merge -
pair native and non
native speakers
Code
sprints?
Why not
doc
sprints?
49
@ixek bit.ly/ato-docs-culture
Slide 50
Slide 50 text
50
Make it a
joy
writing
the docs
@ixek bit.ly/ato-docs-culture
They are the door to
your code and your
team culture
52
Why docs?
Set the right mindset -
for Pull Requests, code
reviews, sprints
planning
Bring people back in the
process
So why docs?
@ixek bit.ly/ato-docs-culture
Slide 53
Slide 53 text
Expose code smells
53
Why docs?
Keeps institutional
knowledge
Protects you against
time churn
So why docs?
@ixek bit.ly/ato-docs-culture
Slide 54
Slide 54 text
Are more likely to stay
around
54
happy people
(developers &
users)
@ixek bit.ly/ato-docs-culture
Slide 55
Slide 55 text
Thank you
& Get in
touch
55
Come visit booth #20
tania.allard[at]microsoft.com
ixek
@ixek bit.ly/ato-docs-culture