Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Sign up for free
Menu
Search
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Pricing
Search
Sign in
Sign up for free
GOV.UK developer docs
Search
Tijmen Brommet
November 20, 2017
Programming
600
0
Share
Embed
Copy iframe code
Copy JS code
Copy link
Start on current slide
GOV.UK developer docs
https://skillsmatter.com/skillscasts/11153-5-ways-to-keep-docs-up-to-date
Tijmen Brommet
November 20, 2017
Transcript
61 slides
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
More Decks by Tijmen Brommet
See All by Tijmen Brommet
Reuse your government's code
tijmenb
0
590
Other Decks in Programming
See All in Programming
Scalaの型でマルチテナントの認可を守る
nextbeatdev
0
160
祈るテストから、探索するテストへ 〜Lincheckではじめる並行処理テスト〜
yyh_gl
0
380
複数ドメインを一つのアプリに統合するFlutterの設計と運用_FlutterKaigi2026登壇資料(須永高弘)
takahirosunaga
0
200
Beyond Chatbots: Agentic UI with Open Standards @W-JAX 2026, München
manfredsteyer
PRO
0
120
疎結合とは何か?ソフトウェア設計における結合バランスについて考える #phpcon_niigata
kajitack
2
380
선언형 햅틱 라이브러리 진동을 소개합니다
l2hyunwoo
1
330
AWS CDKを理解するために公式の定義を深掘って解説してみる / Understanding AWS CDK by Digging into Its Official Definition
akihisaikeda
3
320
Apple Intelligenceとオンデバイス時代の到来
yahir0
0
250
SODA - FACT BOOK(JP)
sodainc
1
40k
作れるエンジニアから、価値を届けるエンジニアへ
ryunakayama
1
320
LLM 101
dalinaum
0
520
プロジェクトコードをキレイキレイしよう!暗黙的な参照を読み解く静的解析
ostk0069
0
220
Featured
See All Featured
From Legacy to Launchpad: Building Startup-Ready Communities
dugsong
0
380
Designing Dashboards & Data Visualisations in Web Apps
destraynor
232
55k
Six Lessons from altMBA
skipperchong
29
4.6k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
56
3.5k
A Soul's Torment
seathinner
9
3.9k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
46
3.1k
How to build an LLM SEO readiness audit: a practical framework
nmsamuel
2
990
Why Our Code Smells
bkeepers
PRO
340
58k
Accessibility Awareness
sabderemane
1
310
Making Projects Easy
brettharned
120
6.9k
Digital Ethics as a Driver of Design Innovation
axbom
PRO
2
550
Digital Projects Gone Horribly Wrong (And the UX Pros Who Still Save the Day) - Dean Schuster
uxyall
2
4k