Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
GOV.UK developer docs
Search
Tijmen Brommet
November 20, 2017
Programming
0
370
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
320
Other Decks in Programming
See All in Programming
決断するための勇気、そのためのBacklog / Courage to make decisions, Backlog for that.
seike460
PRO
4
1.9k
[スクリプト] Swiftの型推論を学ぼう
omochi
0
120
ドメイン・ファーストで考える問題解決に役立つモデル設計 / Domain First Model Design
suzushin54
1
1.5k
Crafting a Own PHP - ウキウキ手作りミニマリストPHP
uzulla
4
1.1k
クソコード動画『カプセル化 Mk-II』 で考える 上手くカプセル化できない理由 / encapsulation2
minodriven
11
8.1k
Ruby製社内ツールのGo移行
bgpat
2
270
Prepare for Jakarta EE 11 - Performance and Developer Productivity
ivargrimstad
0
530
document.write再考
brn
5
2.5k
WinUI 3デモ - "CommunityToolkit.Mvvm"NuGetパッケージ編
andrewkeepcoding
0
140
htmx is fun!
codehex
2
190
DDDはなぜ難しいのか / 良いコードの定義と設計能力の壁
pospome
25
7.7k
プロンプトエンジニアリング入門
tomokusaba
2
990
Featured
See All Featured
The Power of CSS Pseudo Elements
geoffreycrofte
58
4.9k
Mobile First: as difficult as doing things right
swwweet
215
8.5k
Making the Leap to Tech Lead
cromwellryan
123
8.4k
The Illustrated Children's Guide to Kubernetes
chrisshort
28
46k
The Cult of Friendly URLs
andyhume
73
5.6k
Code Reviewing Like a Champion
maltzj
512
39k
[Rails World 2023 - Day 1 Closing Keynote] - The Magic of Rails
eileencodes
1
1.2k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
113
18k
Keith and Marios Guide to Fast Websites
keithpitt
407
22k
What the flash - Photography Introduction
edds
64
11k
Adopting Sorbet at Scale
ufuk
66
8.5k
In The Pink: A Labor of Love
frogandcode
137
21k
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