GOV.UK developer docs

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

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
89

Other Decks in Programming

See All in Programming
D4f04ef104c8fbfc9caa3c80e41692fd?s=48 tsuzuki817
0
230
E48bd6aeb77b88d5762cd5d96e2c397d?s=48 wen_liao
2
910
1a18bf1e50d7d2bdfe52a6c9fceec244?s=48 saiya_moebius
7
1.3k
37618b4d60cf3d1f43f7196253264edc?s=48 numeroanddev
0
270
B7caf463b7dbc6c305ba290ec3c16521?s=48 eroispaziali
0
280
B8403d102456248570005ee7fb2ba0f7?s=48 tooppoo
3
340
37618b4d60cf3d1f43f7196253264edc?s=48 numeroanddev
0
150
C2b1ef3acdb04779e73749a49b5495f9?s=48 nishiuchikazuma
1
260
42a6a049ac8f5265f31858a9509217fb?s=48 uhooi
0
170
110cd4dcaed019b3bd9809e541afdeb6?s=48 okuramasafumi
0
200
1b863be3048c82d20ea84abcce33dc36?s=48 schktjm
0
150
2e7087b86608d4497c209eb9ba14d8f5?s=48 rosylilly
2
3.9k

Featured

See All Featured
9375a9529679f1b42b567a640d775e7d?s=48 schacon
144
6.4k
E190023b66e2b8aa73a842b106920c93?s=48 zenorocha
295
39k
766b9746b59e6f09e280cd33cf4ed419?s=48 skipperchong
2
400
6804f1775cb4babfcc3851298566fbce?s=48 tanoku
256
24k
761be20b5ebd271008bcee1244fc5b52?s=48 matthewcrist
70
7k
06f8b41980eb4c577fa40c41d5030c19?s=48 keathley
12
420
C44e1f7e22c3f23cff7bc130871047ef?s=48 eileencodes
110
24k
F57e2136eb9895eb95ff5dc8a1c02677?s=48 zakiwarfel
87
3.2k
F383c6a4dc55e331bbe2987b622cee6b?s=48 stephaniewalter
256
10k
20bfe76b3d6105641f879fe45cfc9272?s=48 bkeepers
407
57k
Fde6c3a50ca518a909ef35c22c0ee0e4?s=48 destraynor
222
46k
7cbd3f5f922d798cc312eaf596de7ae6?s=48 iamctodd
8
1.2k

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