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
170

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
130

Other Decks in Programming

See All in Programming
79fc33e55cacc42beef647541de24d58?s=48 yasuakiomokawa
0
600
E505897a79eede1a676f92740261e8f8?s=48 kubode
2
190
Bbb17eeeecd3d9d06f4db310ab630a12?s=48 borkdude
1
180
A4d1023b1de7890c67a083d14573882d?s=48 ktgrstsh
0
170
438799c739f93d00abc30fa2da33c543?s=48 rukiadia
3
890
15934fa2aa7b2ce21f091e9b7cffa856?s=48 manfredsteyer
PRO
2
260
B51ca7a51ae1fd06bc536fe83e6113e2?s=48 kaz29
2
130
151a0b14f5914e786e2e104cfb3a9b2f?s=48 orgachem
1
220
A581cbb76555d4854d3264a16fed5d13?s=48 daiki_0816
0
170
D07d36d7d3263da869c7d030ba4a64a6?s=48 y__mattu
0
180
9103dacbfc728d2a583981e7cf854cc4?s=48 fr0gger
2
2.8k
D40b43d43c4d8307c5334f1cb1da03a2?s=48 devinjeon
2
870

Featured

See All Featured
5b9fe87ec1faa67a4599782930f45ec9?s=48 sstephenson
146
12k
20bfe76b3d6105641f879fe45cfc9272?s=48 bkeepers
PRO
322
53k
32de0bd2ba869609d26fd052a4622778?s=48 cromwellryan
104
6.3k
C0b42577cfc2b321be3474618107e933?s=48 samanthasiow
58
6.4k
2bb923c57a1fdc3a2eb484bb8d565fd2?s=48 ufuk
56
5.5k
1519587b1a0febb658c36c94f6272b0d?s=48 roundedbygravity
84
7.9k
5ce91fa49a613cbc3e20d5f96856473f?s=48 edds
56
9.4k
78b475797a14c84799063c7cd073962f?s=48 holman
462
280k
Dad095ea7038f89f760419ce475d5d14?s=48 michaelherold
226
8.6k
Ecdea9b9714877b86cee08458f085481?s=48 trallard
15
820
Aebc2d07a50011e2a30d38435fde564a?s=48 jrom
116
7.2k
9375a9529679f1b42b567a640d775e7d?s=48 schacon
147
6.7k

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