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
   

   View Slide

2. 2
   GOV.UK's

   internal

   developer docs
   

   View Slide

3. 3
   GDS
   

   View Slide

4. 4
   GDS
   

   View Slide

5. 5
   GDS
   

   View Slide

6. 6
   GDS
   

   View Slide

7. 7
   GDS
   

   View Slide

8. 8
   GDS
   2012: live
   2013: + departments
   2014: + agencies
   

   View Slide

9. 9
   GDS
   

   View Slide

10. 10
    GDS
    Result: size & complexity make it hard to
    learn
    

    View Slide

11. 11
    Why is
    documentation so
    hard?
    

    View Slide

12. 12
    GDS
    Nobody reads
    the docs
    Nobody keeps docs
    up to date
    Docs are
    out of date
    Nobody trusts
    the docs
    

    View Slide

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
    

    View Slide

14. 14
    1. Make it fun 

    to update
    

    View Slide

15. 15
    GDS
    

    View Slide

16. 16
    GDS
    

    View Slide

17. 17
    GDS
    

    View Slide

18. 18
    GDS
    

    View Slide

19. 19
    GDS
    

    View Slide

20. 20
    GDS
    

    View Slide

21. 21
    2. Make it 

    easy to find
    

    View Slide

22. 22
    GDS
    Before:
    [REDACTED]
    

    View Slide

23. 23
    GDS
    

    View Slide

24. 24
    GDS
    

    View Slide

25. 25
    GDS
    

    View Slide

26. 26
    GDS
    

    View Slide

27. 27
    GDS
    

    View Slide

28. 28
    GDS
    

    View Slide

29. 29
    3. Optimise 

    reading & writing
    

    View Slide

30. 30
    GDS
    

    View Slide

31. 31
    GDS
    

    View Slide

32. 32
    GDS
    

    View Slide

33. 33
    GDS
    raw.githubusercontent.com/alphagov/
    publishing-api/master/doc/api.md') %>
    

    View Slide

34. 34
    GDS
    

    View Slide

35. 35
    4. Integrate 

    data & config
    

    View Slide

36. 36
    GDS
    

    View Slide

37. 37
    GDS
    

    View Slide

38. 38
    GDS
    

    View Slide

39. 39
    GDS
    

    View Slide

40. 40
    5. Keep it up to date
    

    View Slide

41. 41
    GDS
    Is this accurate?
    ¯\_(ϑ)_/¯
    

    View Slide

42. 42
    GDS
    

    View Slide

43. 43
    GDS
    Date of
    last review &
    owner
    

    View Slide

44. 44
    GDS
    

    View Slide

45. 45
    GDS
    

    View Slide

46. 46
    GDS
    

    View Slide

47. 47
    GDS
    

    View Slide

48. 48
    GDS
    This is a text slide
    

    View Slide

49. GDS
    This is a text slide
    

    View Slide

50. 50
    GDS
    Before: 352 commits by 39 authors
    After: 964 commits by 54 authors
    

    View Slide

51. 51
    Summary
    

    View Slide

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)
    

    View Slide

53. 53
    GDS
    Nobody reads
    the docs
    Nobody keeps docs
    up to date
    Docs are
    out of date
    Nobody trusts
    the docs
    

    View Slide

54. 54
    GDS
    People use docs
    every day
    Docs are kept
    up to date
    Docs are
    mostly accurate
    People trust
    docs
    

    View Slide

55. 55
    GDS
    docs.publishing.service.gov.uk
    github.com/alphagov/govuk-developer-docs
    

    View Slide

56. 56
    GDS
    Thank you!
    @tijmenbr
    

    View Slide

57. 57
    Secret 

    bonus content
    

    View Slide

58. 58
    GDS
    

    View Slide

59. 59
    GDS
    

    View Slide

60. 60
    GDS
    

    View Slide

61. 61
    GDS
    

    View Slide