Upgrade to Pro — share decks privately, control downloads, hide ads and more …

GOOD CODE DOCUMENTS ITSELF AND OTHER LIES: CHANGING WORK CULTURE THROUGH DOCUMENTATION

Tania Allard
November 13, 2019

GOOD CODE DOCUMENTS ITSELF AND OTHER LIES: CHANGING WORK CULTURE THROUGH DOCUMENTATION

Most of us, developers, have heard at some point the phrase “good code documents itself” or any other of its variants such as “documentation outdates easily, the code does not”, “the code should walk you through how to do things”. Mainly as an excuse to not write documentation or to justify the lack thereof. I have worked with many teams and the lack of documentation is often one symptom of high technical debt.

But what if we could turn this around and use documentation like a driver for positive culture change and start paying the critical technical debt? Not only this approach helps the team to faster identify areas that need critical support but also brings in an important factor onto the table ‘empathy’.

In this talk, I will draw on my experiences using documentation as a weapon for positive culture and process change in machine learning and scientific computing environments. I will focus on the processes and approaches that enable the creation of documentation for data scientists, infrastructure and software engineering teams, and clients (without boring the teams to death or halting the technical development).

By the end of the talk team leaders, technical writers, documentation lovers, and software developers alike will have learned efficient techniques to make documentation a first-class citizen of the development cycles. They will also leave with one or two tricks on how to convince even the most reluctant dev to document the code.

Who and why?

This talk is suitable for anyone developing code at any level (or getting started) as well as for team leaders, open source maintainers, community leaders, documentation lovers, basically anyone. Basic understanding of what documentation and code are required.

What I really want people to take away is:

Change the perspective of what code means (it is not a boring piece of writing you need to write but much more)
How documentation can help small and big teams alike to pay technical debt
How you can use ‘documentation’ to change your work culture in a positive way

Tania Allard

November 13, 2019
Tweet

More Decks by Tania Allard

Other Decks in Programming

Transcript

  1. 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

    View full-size slide

  2. 2
    bit.ly/ato-docs-culture
    Get the slides
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  3. 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

    View full-size slide

  4. 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

    View full-size slide

  5. who likes
    writing
    documentation?
    5
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  6. who actually writes
    documentation as a regular
    practice?
    6
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  7. 7
    What if you could change
    your work culture…
    writing documentation?
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  8. 8
    and pay some technical debt?
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  9. What is technical debt?

    View full-size slide

  10. It’s like
    the
    monster
    under
    your bed
    10
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  11. Technical debt
    A series of bad
    decisions
    11
    WHAT I DO
    Leading to error
    prone code &
    architecture
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  12. 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

    View full-size slide

  13. What
    decisions
    were made
    in the past?
    That prevent
    me from
    getting
    stuff done
    today
    @ixek

    View full-size slide

  14. What
    causes
    technical
    debt?
    14
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  15. 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

    View full-size slide

  16. Unnecessary
    complexity
    16
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  17. 17
    All of our code is a pile
    of garbage… so nobody
    will notice if I add to
    the pile
    An
    already
    broken
    culture
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  18. 18
    Identifying technical
    debt
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  19. 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

    View full-size slide

  20. 20
    https://xkcd.com/2054/
    House of cards effect - Infra smells
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  21. 21
    https://xkcd.com/1794/
    Everything is on FIRE - all the time
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  22. 22
    Courtesy of Ashley Mcnamara
    Everything is on FIRE - all the time
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  23. 23
    Unstable or
    underutilized
    data
    dependencies
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  24. 24
    Pipeline
    jungles
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  25. 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

    View full-size slide

  26. 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

    View full-size slide

  27. 27
    Story
    time
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  28. 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

    View full-size slide

  29. 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

    View full-size slide

  30. 30
    You are
    given a
    present
    ● You will be miserable all the
    time
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  31. Write the Docs!!
    Make the Docs
    valuable
    31
    Courtesy of Ashley Mcnamara
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  32. 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

    View full-size slide

  33. 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

    View full-size slide

  34. 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

    View full-size slide

  35. 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

    View full-size slide

  36. 36
    https://alexjs.com/ VIsual Studio Code Extension https://cda.ms/146
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  37. “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

    View full-size slide

  38. 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

    View full-size slide

  39. If you
    cannot
    use the
    mindful
    structure
    You might need to refactor
    39
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  40. 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

    View full-size slide

  41. 41
    https://azure.microsoft.com/en-us/resources/samples/?sort=0
    Give them useful starting points
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  42. 42
    Make the abstract tangible
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  43. 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

    View full-size slide

  44. 44
    https://speakerdeck.com/inesmontani/let-them-write-code-keynote-pycon-india-2019
    Design patterns
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  45. 45
    https://speakerdeck.com/inesmontani/let-them-write-code-keynote-pycon-india-2019
    Design patterns and users
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  46. 46
    Bye bye manual docs
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  47. 47
    https://github.com/pycco-docs/pycco
    Bye bye manual docs
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  48. 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

    View full-size slide

  49. ● 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

    View full-size slide

  50. 50
    Make it a
    joy
    writing
    the docs
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  51. 51
    Recognise
    docs
    writers
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  52. 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

    View full-size slide

  53. Expose code smells
    53
    Why docs?
    Keeps institutional
    knowledge
    Protects you against
    time churn
    So why docs?
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  54. Are more likely to stay
    around
    54
    happy people
    (developers &
    users)
    @ixek bit.ly/ato-docs-culture

    View full-size slide

  55. Thank you
    & Get in
    touch
    55
    Come visit booth #20
    tania.allard[at]microsoft.com
    ixek
    @ixek bit.ly/ato-docs-culture

    View full-size slide