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

GOV.UK developer docs

GOV.UK developer docs

Tijmen Brommet

November 20, 2017
Tweet

More Decks by Tijmen Brommet

Other Decks in Programming

Transcript

  1. Tijmen Brommet
    Lead developer, GOV.UK

    Government Digital Service

    @tijmenbr

    View Slide

  2. 2
    GOV.UK's

    internal

    developer docs

    View Slide

  3. 3
    GDS

    View Slide

  4. 4
    GDS

    View Slide

  5. 5
    GDS

    View Slide

  6. 6
    GDS

    View Slide

  7. 7
    GDS

    View Slide

  8. 8
    GDS
    2012: live
    2013: + departments
    2014: + agencies

    View Slide

  9. 9
    GDS

    View Slide

  10. 10
    GDS
    Result: size & complexity make it hard to
    learn

    View Slide

  11. 11
    Why is
    documentation so
    hard?

    View Slide

  12. 12
    GDS
    Nobody reads
    the docs
    Nobody keeps docs
    up to date
    Docs are
    out of date
    Nobody trusts
    the docs

    View Slide

  13. 13
    GDS
    How?
    1. Make it fun to update
    2. Make it easy to find
    3. Optimise reading & writing
    4. Integrate data & config
    5. Keep it up to date

    View Slide

  14. 14
    1. Make it fun 

    to update

    View Slide

  15. 15
    GDS

    View Slide

  16. 16
    GDS

    View Slide

  17. 17
    GDS

    View Slide

  18. 18
    GDS

    View Slide

  19. 19
    GDS

    View Slide

  20. 20
    GDS

    View Slide

  21. 21
    2. Make it 

    easy to find

    View Slide

  22. 22
    GDS
    Before:
    [REDACTED]

    View Slide

  23. 23
    GDS

    View Slide

  24. 24
    GDS

    View Slide

  25. 25
    GDS

    View Slide

  26. 26
    GDS

    View Slide

  27. 27
    GDS

    View Slide

  28. 28
    GDS

    View Slide

  29. 29
    3. Optimise 

    reading & writing

    View Slide

  30. 30
    GDS

    View Slide

  31. 31
    GDS

    View Slide

  32. 32
    GDS

    View Slide

  33. 33
    GDS
    raw.githubusercontent.com/alphagov/
    publishing-api/master/doc/api.md') %>

    View Slide

  34. 34
    GDS

    View Slide

  35. 35
    4. Integrate 

    data & config

    View Slide

  36. 36
    GDS

    View Slide

  37. 37
    GDS

    View Slide

  38. 38
    GDS

    View Slide

  39. 39
    GDS

    View Slide

  40. 40
    5. Keep it up to date

    View Slide

  41. 41
    GDS
    Is this accurate?
    ¯\_(ϑ)_/¯

    View Slide

  42. 42
    GDS

    View Slide

  43. 43
    GDS
    Date of
    last review &
    owner

    View Slide

  44. 44
    GDS

    View Slide

  45. 45
    GDS

    View Slide

  46. 46
    GDS

    View Slide

  47. 47
    GDS

    View Slide

  48. 48
    GDS
    This is a text slide

    View Slide

  49. GDS
    This is a text slide

    View Slide

  50. 50
    GDS
    Before: 352 commits by 39 authors
    After: 964 commits by 54 authors

    View Slide

  51. 51
    Summary

    View Slide

  52. 52
    GDS
    1. Make it fun to update
    2. Make it easy to find
    3. Optimise reading & writing
    4. Integrate data & config
    5. Keep it up to date (with a guard dog)

    View Slide

  53. 53
    GDS
    Nobody reads
    the docs
    Nobody keeps docs
    up to date
    Docs are
    out of date
    Nobody trusts
    the docs

    View Slide

  54. 54
    GDS
    People use docs
    every day
    Docs are kept
    up to date
    Docs are
    mostly accurate
    People trust
    docs

    View Slide

  55. 55
    GDS
    docs.publishing.service.gov.uk
    github.com/alphagov/govuk-developer-docs

    View Slide

  56. 56
    GDS
    Thank you!
    @tijmenbr

    View Slide

  57. 57
    Secret 

    bonus content

    View Slide

  58. 58
    GDS

    View Slide

  59. 59
    GDS

    View Slide

  60. 60
    GDS

    View Slide

  61. 61
    GDS

    View Slide