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

You're doing documentation wrong… and so am I

You're doing documentation wrong… and so am I

As developers, we’re always asked to write more documentation. Some of us even do it without being asked. But look around the web and you’ll see countless gems, applications and source code examples whose documentation is either missing or makes no sense. How can we make little changes to the way we think about documentation to make things better?

6f9eea37d3dbcfd7a49b0369cf826bbd?s=128

Scott Matthewman

April 09, 2018
Tweet

Transcript

  1. LRUG, APRIL 2018 Scott Matthewman

  2. YOU ARE DOING DOCUMENTATION WRONG (…AND SO AM I) Scott

    Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  3. YOU ARE DOING DOCUMENTATION WRONG Scott Matthewman – LRUG, April

    2018 – @scottm – scottmatthewman
  4. WE ARE DOING DOCUMENTATION WRONG Scott Matthewman – LRUG, April

    2018 – @scottm – scottmatthewman
  5. TECHNICAL DEBT Scott Matthewman – LRUG, April 2018 – @scottm

    – scottmatthewman
  6. TECHNICAL DEBT “THE REFACTORING EFFORT NEEDED TO ADD A FEATURE

    NON-INVASIVELY” — Michael C. Feathers Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  7. https://skillsmatter.com/courses/472 Scott Matthewman – LRUG, April 2018 – @scottm –

    scottmatthewman
  8. https://skillsmatter.com/skillscasts/11433 Scott Matthewman – LRUG, April 2018 – @scottm –

    scottmatthewman
  9. TECHNICAL DEBT Scott Matthewman – LRUG, April 2018 – @scottm

    – scottmatthewman
  10. DOCUMENTATION DEBT Scott Matthewman – LRUG, April 2018 – @scottm

    – scottmatthewman
  11. TECHNICAL DEBT THE REFACTORING EFFORT NEEDED TO ADD A FEATURE

    NON-INVASIVELY Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  12. DOCUMENTATION DEBT ? Scott Matthewman – LRUG, April 2018 –

    @scottm – scottmatthewman
  13. DOCUMENTATION DEBT THE INTELLECTUAL EFFORT NEEDED FOR SOMEONE TO USE

    CODE UNASSISTED Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  14. “I’VE FOUND A GEM THAT I THINK WILL DO THE

    JOB... BUT THE DOCUMENTATION’S NOT VERY CLEAR, SO IT’LL TAKE ME A WHILE TO FIND OUT” Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  15. MAKING OURSELVES BE BETTER AT DOCUMENTATION Scott Matthewman – LRUG,

    April 2018 – @scottm – scottmatthewman
  16. QUESTIONS WE NEED TO ANSWER Why What Who Where When

    How Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  17. WHAT COUNTS AS DOCUMENTATION? Scott Matthewman – LRUG, April 2018

    – @scottm – scottmatthewman
  18. WHO IS THE DOCUMENTATION FOR? Scott Matthewman – LRUG, April

    2018 – @scottm – scottmatthewman
  19. UNLESS WE KNOW WHO THE READER IS, WE CANNOT WRITE

    FOR THEM EFFECTIVELY AND WITH CLARITY Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  20. READER PERSONAS Scott Matthewman – LRUG, April 2018 – @scottm

    – scottmatthewman
  21. INTERNAL READERS EXTERNAL READERS Scott Matthewman – LRUG, April 2018

    – @scottm – scottmatthewman
  22. EXAMPLES OF INTERNAL READERS Scott Matthewman – LRUG, April 2018

    – @scottm – scottmatthewman
  23. EXAMPLES OF INTERNAL READERS ▸ New starters Scott Matthewman –

    LRUG, April 2018 – @scottm – scottmatthewman
  24. EXAMPLES OF INTERNAL READERS ▸ New starters ▸ Other teams

    Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  25. EXAMPLES OF INTERNAL READERS ▸ New starters ▸ Other teams

    ▸ Support desk Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  26. EXAMPLES OF INTERNAL READERS ▸ New starters ▸ Other teams

    ▸ Support desk ▸ Your future selves Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  27. EXAMPLES OF EXTERNAL READERS Scott Matthewman – LRUG, April 2018

    – @scottm – scottmatthewman
  28. EXAMPLES OF EXTERNAL READERS ▸ Clients you’re building code for

    Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  29. EXAMPLES OF EXTERNAL READERS ▸ Clients you’re building code for

    ▸ Users of your gems Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  30. EXAMPLES OF EXTERNAL READERS ▸ Clients you’re building code for

    ▸ Users of your gems ▸ Regulatory purposes Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  31. WHO'S NOT ON YOUR PERSONAS LIST? Scott Matthewman – LRUG,

    April 2018 – @scottm – scottmatthewman
  32. YOU Scott Matthewman – LRUG, April 2018 – @scottm –

    scottmatthewman
  33. EXAMPLES OF INTERNAL READERS ▸ New starters ▸ Other teams

    ▸ Support desk ▸ Your future self Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  34. THE PERSON WHO'S JUST WRITTEN THE CODE DOES NOT USUALLY

    NEED DOCUMENTATION Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  35. THE PERSON WHO'S JUST WRITTEN THE CODE IS USUALLY THE

    ONE WHO DOCUMENTS IT Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  36. Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman

  37. “WHAT'S UP, DOCS?” BIKESHED.FM/137 Scott Matthewman – LRUG, April 2018

    – @scottm – scottmatthewman
  38. “I’M NOT THE RIGHT PERSON TO DOCUMENT THIS. BECAUSE I’M

    GOING TO WRITE DOCS FROM MY POINT OF VIEW… Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  39. …I DON’T KNOW WHAT THEY’RE LOOKING FOR THAT ISN’T THERE,

    OR WHERE THINGS FALL SHORT OF EXPLAINING THEM EFFECTIVELY.” — Sean Griffin Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  40. I AM NOT MY OWN READER PERSONA Scott Matthewman –

    LRUG, April 2018 – @scottm – scottmatthewman
  41. CONTEXT Scott Matthewman – LRUG, April 2018 – @scottm –

    scottmatthewman
  42. CONTEXT GIVES US THE SKILLS AND KNOWLEDGE TO WRITE THE

    DOCUMENTATION Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  43. CONTEXT IS WHAT READERS OF DOCUMENTATION ARE MISSING IN THE

    FIRST PLACE Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  44. SHOULD I USE IT? Scott Matthewman – LRUG, April 2018

    – @scottm – scottmatthewman
  45. HOW DO I USE IT? Scott Matthewman – LRUG, April

    2018 – @scottm – scottmatthewman
  46. WHY ISN'T IT WORKING? Scott Matthewman – LRUG, April 2018

    – @scottm – scottmatthewman
  47. CAN I STILL USE IT? Scott Matthewman – LRUG, April

    2018 – @scottm – scottmatthewman
  48. ▸ Should I use it? ▸ How do I use

    it? ▸ Why isn't it working? ▸ Can I still use it? ▸ etc. Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  49. TECHNIQUES Scott Matthewman – LRUG, April 2018 – @scottm –

    scottmatthewman
  50. PAIRING WITH SOMEONE WHO DIDN'T WRITE THE CODE Scott Matthewman

    – LRUG, April 2018 – @scottm – scottmatthewman
  51. CONTEXT SWITCHING Scott Matthewman – LRUG, April 2018 – @scottm

    – scottmatthewman
  52. BUILD A DOCUMENTATION STEP INTO YOUR DEVELOPMENT PROCESS Scott Matthewman

    – LRUG, April 2018 – @scottm – scottmatthewman
  53. ENCOURAGE AND PRIORITISE DOCUMENTATION-ONLY PULL REQUESTS Scott Matthewman – LRUG,

    April 2018 – @scottm – scottmatthewman
  54. NEVER USE “JUST” OR “SIMPLY” Scott Matthewman – LRUG, April

    2018 – @scottm – scottmatthewman
  55. http://bradfrost.com/blog/post/just/ Scott Matthewman – LRUG, April 2018 – @scottm –

    scottmatthewman
  56. Why Who What When Where How Scott Matthewman – LRUG,

    April 2018 – @scottm – scottmatthewman
  57. WHERE AND HOW DOCUMENTATION DEBT READER PERSONAS Scott Matthewman –

    LRUG, April 2018 – @scottm – scottmatthewman
  58. TECHNICAL DEBT → DOCUMENTATION DEBT USER PERSONAS → READER PERSONAS

    Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  59. Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman

  60. “DON’T CALL IT A RESOLUTION” GIMLETMEDIA.COM/THE-NOD/BONUS-DONT-CALL-RESOLUTION Scott Matthewman – LRUG,

    April 2018 – @scottm – scottmatthewman
  61. “REMEMBER THAT YOU’RE TRYING YOUR BEST… AND THEN TRY YOUR

    BEST.” — Brittany Luse Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  62. THANK YOU SLIDES AVAILABLE AT MTTHW.MN/DOCS-WRONG Scott Matthewman – LRUG,

    April 2018 – @scottm – scottmatthewman