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

GOV.UK developer docs

Fca8cbc21334fe574db2d0343facf873?s=47 Tijmen Brommet
November 20, 2017
Programming
0
160

GOV.UK developer docs

https://skillsmatter.com/skillscasts/11153-5-ways-to-keep-docs-up-to-date

Fca8cbc21334fe574db2d0343facf873?s=128

Tijmen Brommet

November 20, 2017
Tweet

More Decks by Tijmen Brommet

See All by Tijmen Brommet
Fca8cbc21334fe574db2d0343facf873?s=48 tijmenb
0
120

Other Decks in Programming

See All in Programming
3742ae4f74e584aed4f41c405232c3bb?s=48 yaamaa
0
410
E473e5af1263c050599921981db46068?s=48 akatsukinewgrad
0
160
51ae114c2809ff0d2945c751efa7cffc?s=48 canon1ky
3
350
079f41894122acf92719f5558dcaf944?s=48 dictoss
0
160
6378a3035de0b841dba4ab82bd7f624d?s=48 blendthink
0
410
3931098ae486b6df619050c63e24f6cc?s=48 osyo
1
370
Cfbe23392787cb3ad4689c5f72463fcc?s=48 makicamel
1
170
2102a6b8760bd6f57f672805723dd83a?s=48 line_developers_tw
1
430
270b0c7883545117a9a618dc7ca7cc83?s=48 xrdnk
0
130
22e056dcb79e14363e844f1e57986325?s=48 aratayokoyama
0
200
2102a6b8760bd6f57f672805723dd83a?s=48 line_developers_tw
0
460
35c158f57df6814ad809f7471f4123ed?s=48 loleg
0
200

Featured

See All Featured
8081b26e05bb4354f7d65ffc34cbbd67?s=48 chriscoyier
780
240k
D8fc2580cfaca035f666d9e4ee79a7f7?s=48 mongodb
23
3.8k
Ae14cc4491ac334f9cd23f9f93b4305e?s=48 orderedlist
PRO
329
35k
Ded01cdab114abe4ec13511e4c25b9bb?s=48 andyhume
62
3.4k
C157b16234f1e75e8eac3698c1d4414a?s=48 ddemaree
274
31k
7fa6101cd43067653cf4ac6c7ca54305?s=48 akmur
252
19k
4394ceb8b277f35ee3da7030384efb5d?s=48 davidbonilla
69
3.5k
E6c6e133e74c3b83f04d2861deaa1c20?s=48 searls
204
35k
F716e5f737fcfb03f2cf8d1a184f1dbe?s=48 nonsquared
81
3.3k
E190023b66e2b8aa73a842b106920c93?s=48 zenorocha
297
39k
Dafc4723e9a1c067796c0fec6f509774?s=48 lemiorhan
626
42k
F383c6a4dc55e331bbe2987b622cee6b?s=48 stephaniewalter
260
11k

Transcript

  1. Tijmen Brommet Lead developer, GOV.UK
 Government Digital Service
 @tijmenbr

  2. 2 GOV.UK's
 internal
 developer docs

  3. 3 GDS

  4. 4 GDS

  5. 5 GDS

  6. 6 GDS

  7. 7 GDS

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

  9. 9 GDS

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

    learn

  11. 11 Why is documentation so hard?

  12. 12 GDS Nobody reads the docs Nobody keeps docs up

    to date Docs are out of date Nobody trusts the docs

  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

  14. 14 1. Make it fun 
 to update

  15. 15 GDS

  16. 16 GDS

  17. 17 GDS

  18. 18 GDS

  19. 19 GDS

  20. 20 GDS

  21. 21 2. Make it 
 easy to find

  22. 22 GDS Before: [REDACTED]

  23. 23 GDS

  24. 24 GDS

  25. 25 GDS

  26. 26 GDS

  27. 27 GDS

  28. 28 GDS

  29. 29 3. Optimise 
 reading & writing

  30. 30 GDS

  31. 31 GDS

  32. 32 GDS

  33. 33 GDS <%= HTTP.get('https:// raw.githubusercontent.com/alphagov/ publishing-api/master/doc/api.md') %>

  34. 34 GDS

  35. 35 4. Integrate 
 data & config

  36. 36 GDS

  37. 37 GDS

  38. 38 GDS

  39. 39 GDS

  40. 40 5. Keep it up to date

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

  42. 42 GDS

  43. 43 GDS Date of last review & owner

  44. 44 GDS

  45. 45 GDS

  46. 46 GDS

  47. 47 GDS

  48. 48 GDS This is a text slide

  49. GDS This is a text slide

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

    commits by 54 authors

  51. 51 Summary

  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)

  53. 53 GDS Nobody reads the docs Nobody keeps docs up

    to date Docs are out of date Nobody trusts the docs

  54. 54 GDS People use docs every day Docs are kept

    up to date Docs are mostly accurate People trust docs

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

  56. 56 GDS Thank you! @tijmenbr

  57. 57 Secret 
 bonus content

  58. 58 GDS

  59. 59 GDS

  60. 60 GDS

  61. 61 GDS