Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
GOV.UK developer docs
Tijmen Brommet
November 20, 2017
Programming
0
280
GOV.UK developer docs
https://skillsmatter.com/skillscasts/11153-5-ways-to-keep-docs-up-to-date
Tijmen Brommet
November 20, 2017
Tweet
Share
More Decks by Tijmen Brommet
See All by Tijmen Brommet
Reuse your government's code
tijmenb
0
200
Other Decks in Programming
See All in Programming
Kotlin 最新動向2022 #tfcon #techfeed
ntaro
1
770
Where and how to run UI tests (Droidcon Lisbon & Android Makers, Paris)
nonews
0
110
mrubyを1300円のボードで動かそう
yuuu
0
170
近況PHP / PHP in now a days
uzulla
4
1.3k
microCMS × Shopifyで、ECサイトがリニューアル後急成長した話
microcms
0
440
Microsoft Teams の 会議アプリ開発のはじめかた / How to start Microsoft Teams app development
karamem0
0
1.4k
職場にPythonistaを増やす方法
soogie
0
170
書籍『良いコード/悪いコードで学ぶ設計入門』でエンジニアリングの当たり前を変える
minodriven
3
1k
Is Rust a great language for building Kubernetes ecosystem
deepu105
0
140
Nix for Scala folks
kubukoz
0
120
Managing gRPC with Wire
oldergod
2
150
WindowsコンテナDojo:第2回 Windowsコンテナアプリのビルド、公開、デプロイ
oniak3ibm
PRO
0
130
Featured
See All Featured
Practical Orchestrator
shlominoach
178
8.6k
Debugging Ruby Performance
tmm1
65
10k
Visualization
eitanlees
124
11k
How STYLIGHT went responsive
nonsquared
85
3.9k
Clear Off the Table
cherdarchuk
79
280k
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
37
3.2k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
236
1M
How to Ace a Technical Interview
jacobian
265
21k
Code Review Best Practice
trishagee
41
6.7k
Facilitating Awesome Meetings
lara
29
3.9k
Testing 201, or: Great Expectations
jmmastey
21
5.4k
jQuery: Nuts, Bolts and Bling
dougneiner
56
6.4k
Transcript
Tijmen Brommet Lead developer, GOV.UK Government Digital Service @tijmenbr
2 GOV.UK's internal developer docs
3 GDS
4 GDS
5 GDS
6 GDS
7 GDS
8 GDS 2012: live 2013: + departments 2014: + agencies
9 GDS
10 GDS Result: size & complexity make it hard to
learn
11 Why is documentation so hard?
12 GDS Nobody reads the docs Nobody keeps docs up
to date Docs are out of date Nobody trusts the docs
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 1. Make it fun to update
15 GDS
16 GDS
17 GDS
18 GDS
19 GDS
20 GDS
21 2. Make it easy to find
22 GDS Before: [REDACTED]
23 GDS
24 GDS
25 GDS
26 GDS
27 GDS
28 GDS
29 3. Optimise reading & writing
30 GDS
31 GDS
32 GDS
33 GDS <%= HTTP.get('https:// raw.githubusercontent.com/alphagov/ publishing-api/master/doc/api.md') %>
34 GDS
35 4. Integrate data & config
36 GDS
37 GDS
38 GDS
39 GDS
40 5. Keep it up to date
41 GDS Is this accurate? ¯\_(ϑ)_/¯
42 GDS
43 GDS Date of last review & owner
44 GDS
45 GDS
46 GDS
47 GDS
48 GDS This is a text slide
GDS This is a text slide
50 GDS Before: 352 commits by 39 authors After: 964
commits by 54 authors
51 Summary
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 GDS Nobody reads the docs Nobody keeps docs up
to date Docs are out of date Nobody trusts the docs
54 GDS People use docs every day Docs are kept
up to date Docs are mostly accurate People trust docs
55 GDS docs.publishing.service.gov.uk github.com/alphagov/govuk-developer-docs
56 GDS Thank you! @tijmenbr
57 Secret bonus content
58 GDS
59 GDS
60 GDS
61 GDS