GOV.UK developer docs

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

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
100

Other Decks in Programming

See All in Programming
8b0e9a3684bd29ecece29db2582e38ae?s=48 norioikedo
0
270
0c8f21e528a49d714bd0e1629054bdf4?s=48 gyugyu
0
110
Ffc500baeba9a1024e2c8273203c9f90?s=48 raulh82vlc
3
1.5k
9987516c273a7874b12b742e7aef828f?s=48 smellman
0
190
6dd0483f1353a4a359e92633cfd65c64?s=48 wasabeef
27
6.1k
A6ba8150ec3d9e5f2c675ef8bd652ff5?s=48 vailkako
0
180
264b44c0c6d60336f8b6a0fbab118984?s=48 mmazour
0
140
8c10fdf7a2e8ebb97041029c5efd914f?s=48 erimatsu
0
130
0fb2ce77513181750c384115cd0bc937?s=48 ksukenobe
2
280
A030c34a2bc0d0610b4d87f8c56a2ab7?s=48 masatomix
0
140
C8097f17712da7f3123f28a4d3e6bdb9?s=48 androhi
0
490
C0eb1445cda9489ebf8c31c367fec3fb?s=48 exoego
1
370

Featured

See All Featured
1f74b13f1e5c6c69cb5d7fbaabb1e2cb?s=48 sferik
609
54k
48c098b6579220a67a6ba949be6e4b5a?s=48 revolveconf
197
9.5k
C1daf20e5c49ff910745198ef9869ac2?s=48 hatefulcrawdad
257
16k
96270e4c3e5e9806cf7245475c00b275?s=48 addyosmani
493
110k
7fa6101cd43067653cf4ac6c7ca54305?s=48 akmur
252
19k
D8fc2580cfaca035f666d9e4ee79a7f7?s=48 mongodb
23
3.7k
F383c6a4dc55e331bbe2987b622cee6b?s=48 stephaniewalter
256
11k
7559f6cff1f5efc2d210965febd4d71c?s=48 bermonpainter
339
26k
1b75d89772b7eea1f6c89fbf362607d9?s=48 moore
125
21k
C9b18d9dff88a9dd2393364c2b3b21bd?s=48 colly
185
14k
8ec1383b240b5ba15ffb9743fceb3c0e?s=48 philnash
4
290
A9a491b0fcbe0fbce3d64063a37add99?s=48 rmw
10
630

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