GOV.UK developer docs

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

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