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
180

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
150

Other Decks in Programming

See All in Programming
15934fa2aa7b2ce21f091e9b7cffa856?s=48 manfredsteyer
PRO
0
110
9a805d1d3fb2ca4943cb240dee106d5a?s=48 kawakin
1
140
583e920a7e9238a1c21e923025f8f641?s=48 elainenaomi
4
170
B8e501d93b98a553abf0b5cee0c33503?s=48 yasaichi
36
12k
9adb9a67e73d93190e1d07d077a9aae7?s=48 ykkc
4
330
585b6bd646ae00cd1025309c912d922f?s=48 saten
5
780
9f33218af7ae5c04e102fcc3076f2f5c?s=48 yhkaplan
0
420
Af64bc38c0ffcfcabdf430759ee491ce?s=48 lovee
1
410
D5744e72b6a5e6673f991cab987a31ab?s=48 siketyan
2
140
8f84b7d8869ef6005d89b378e8661f7c?s=48 masuda220
0
120
4ce43cd2535d0afe50065a743af646e9?s=48 dianaarnos
1
210
50443a0c666aa1020f2f757582e6e45c?s=48 suzukiot
0
200

Featured

See All Featured
F716e5f737fcfb03f2cf8d1a184f1dbe?s=48 nonsquared
84
3.6k
3ab1249be442027903e1180025340b3f?s=48 reverentgeek
171
7.7k
651dcfe41723207fbb0aa044a4f7c07f?s=48 dotmariusz
99
5.7k
5f2da528927a2ec9ba4fec2069cbc958?s=48 kneath
224
15k
245cee81a9c424266e5e401d844ea881?s=48 lara
595
62k
7c8469ee8c9e594c65c59b919626c08d?s=48 scottboms
253
11k
4394ceb8b277f35ee3da7030384efb5d?s=48 davidbonilla
75
3.8k
7653c7c449918ff6542880a8c284f5e7?s=48 jponch
106
5.3k
20bfe76b3d6105641f879fe45cfc9272?s=48 bkeepers
PRO
324
54k
B6a8f005f39d23ffc930508ac9da68b9?s=48 vanstee
122
5.1k
B3ace07412a5178ea778e7eec161fc0a?s=48 jcasabona
10
740
78b475797a14c84799063c7cd073962f?s=48 holman
294
130k

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