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?

Scott Matthewman

April 09, 2018
Tweet

More Decks by Scott Matthewman

Other Decks in Technology

Transcript

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

    Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  2. TECHNICAL DEBT “THE REFACTORING EFFORT NEEDED TO ADD A FEATURE

    NON-INVASIVELY” — Michael C. Feathers Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  3. TECHNICAL DEBT THE REFACTORING EFFORT NEEDED TO ADD A FEATURE

    NON-INVASIVELY Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  4. DOCUMENTATION DEBT THE INTELLECTUAL EFFORT NEEDED FOR SOMEONE TO USE

    CODE UNASSISTED Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  5. “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
  6. QUESTIONS WE NEED TO ANSWER Why What Who Where When

    How Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  7. UNLESS WE KNOW WHO THE READER IS, WE CANNOT WRITE

    FOR THEM EFFECTIVELY AND WITH CLARITY Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  8. EXAMPLES OF INTERNAL READERS ▸ New starters Scott Matthewman –

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

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

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

    ▸ Support desk ▸ Your future selves Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  12. EXAMPLES OF EXTERNAL READERS ▸ Clients you’re building code for

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

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

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

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

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

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

    ONE WHO DOCUMENTS IT Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  19. “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
  20. …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
  21. I AM NOT MY OWN READER PERSONA Scott Matthewman –

    LRUG, April 2018 – @scottm – scottmatthewman
  22. CONTEXT GIVES US THE SKILLS AND KNOWLEDGE TO WRITE THE

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

    FIRST PLACE Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  24. HOW DO I USE IT? Scott Matthewman – LRUG, April

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

    2018 – @scottm – scottmatthewman
  26. ▸ 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
  27. PAIRING WITH SOMEONE WHO DIDN'T WRITE THE CODE Scott Matthewman

    – LRUG, April 2018 – @scottm – scottmatthewman
  28. BUILD A DOCUMENTATION STEP INTO YOUR DEVELOPMENT PROCESS Scott Matthewman

    – LRUG, April 2018 – @scottm – scottmatthewman
  29. Why Who What When Where How Scott Matthewman – LRUG,

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

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

    Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman
  32. “REMEMBER THAT YOU’RE TRYING YOUR BEST… AND THEN TRY YOUR

    BEST.” — Brittany Luse Scott Matthewman – LRUG, April 2018 – @scottm – scottmatthewman