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

Let Me Write That Down For You

Let Me Write That Down For You

The importance of documenting software.

Presentation given at PHP Warwickshire.

Stuart Herbert

January 26, 2017
Tweet

More Decks by Stuart Herbert

Other Decks in Programming

Transcript

  1. @GanbaroDigital Today’s Talk 1. Why Do Docs Matter? 2. Why

    Do I Doc? 3. What To Doc? 4. Tools For Docs
  2. @GanbaroDigital ?? ?? What do you write in your comments?

    Docblocks? Inline comments? Explain bug fixes?
  3. @GanbaroDigital Code Cannot Tell You • What the requirement was

    • Why the requirement is like that • Why the software was designed like that
  4. @GanbaroDigital ?? ?? Who here writes 100% of the code

    in their project / app / component?
  5. @GanbaroDigital Do You Still Agree? 1. The source is all

    you need 2. Code is the documentation 3. I’ll remember everything I did and why 4. I’m the only one who will ever touch the code
  6. @GanbaroDigital Budget Rules Of Thumb • If coding takes X

    amount of time / effort • Testing takes up to 40% of X • Documentation takes up to 20% of X
  7. @GanbaroDigital “ Just look at CVs and covering letters to

    see how little practice developers have at writing.
  8. @GanbaroDigital Point Of Use • HTTP / Service APIs •

    Package / Component / Library APIs • Source Code!
  9. @GanbaroDigital Why Slate For APIs? 1. Static site - docs

    can live in Git 2. Can mix tutorials and reference docs 3. Examples in multiple languages
  10. @GanbaroDigital Why Couscous For Libraries? 1. Static site - docs

    can live with your code 2. Can mix tutorials and reference docs 3. Easy to incorporate into your CI flow