A Documentation Crash Course, LinuxCon 2016

Chris Ward
Chris WardTechnical Writer and Blogger at Contentful
A Documentation
Crash Course
…for developers
LinuxCon, Berlin

@chrischinch
What’s one of the first
things you look at
with a new project?
• W
• W
• W
ho are you writing for?
hat are they trying to achieve?
hy are you writing this?
Youhavehopefullyansweredthesebeforedevelopment…
Assume nothing
Refine your
concept(s)
API docs are (not)
always enough
It’s not a manual
Interactivity
A Documentation Crash Course, LinuxCon 2016
A Documentation Crash Course, LinuxCon 2016
A Documentation Crash Course, LinuxCon 2016
Language
Selected highlights in (mostly) English,
sorry…
Involve the reader
“function takes
parameter x and
returns value y”
“You can use
function to return
the value of y based
on x”
Passive vs Active
“function can be
used to return the
number of y based
on x”
“Holiday approval
will be notified in
due course”
Keep it short
“If I Had More
Time, I Would Have
Written a Shorter
Letter”
– Pascal, Locke, Franklin, Thoreau, Cicero, Wilson?
Structure
A Documentation Crash Course, LinuxCon 2016
Consistency
Tools
In brief…
Format and editing
Management and
rendering
Testing, linting and
automating
Write your own
Want More?
• www.meetup.com/Write-The-Docs-
Berlin
• slack.writethedocs.org
–Me (maybe)
“Documentation
isn’t just for
developers”
Thank You!
Chris Ward
contentful.com
gregariousmammal.com
@chrischinch
I have stickers and merchandise!
1 of 31

Recommended

Why You're A Bad PHP Programmer by
Why You're A Bad PHP ProgrammerWhy You're A Bad PHP Programmer
Why You're A Bad PHP ProgrammerKLabCyscorpions-TechBlog
972 views18 slides
Effective JavaScript by
Effective JavaScriptEffective JavaScript
Effective JavaScriptguest863345c
945 views35 slides
Why you should come to DrupalSouth by
Why you should come to DrupalSouthWhy you should come to DrupalSouth
Why you should come to DrupalSouthChris Ward
1K views12 slides
Electron - Solving our cross platform dreams? by
Electron - Solving our cross platform dreams?Electron - Solving our cross platform dreams?
Electron - Solving our cross platform dreams?Chris Ward
651 views19 slides
Entrez dans le mouvement Maker à l’aide des technologies Microsoft by
Entrez dans le mouvement Maker à l’aide des technologies MicrosoftEntrez dans le mouvement Maker à l’aide des technologies Microsoft
Entrez dans le mouvement Maker à l’aide des technologies MicrosoftFabrice BARBIN
725 views34 slides
Content Management Systems and Refactoring - Drupal, WordPress and eZ Publish by
Content Management Systems and Refactoring - Drupal, WordPress and eZ PublishContent Management Systems and Refactoring - Drupal, WordPress and eZ Publish
Content Management Systems and Refactoring - Drupal, WordPress and eZ PublishJani Tarvainen
1.4K views30 slides

More Related Content

Viewers also liked

Mongrel2, a short introduction by
Mongrel2, a short introductionMongrel2, a short introduction
Mongrel2, a short introductionPaolo Negri
1.9K views43 slides
Offre développeur Javascript Back-end by
Offre développeur Javascript Back-endOffre développeur Javascript Back-end
Offre développeur Javascript Back-endSite Analyzer
916 views5 slides
Contentful Berlin Offices by
Contentful Berlin OfficesContentful Berlin Offices
Contentful Berlin OfficesIrina Botea
163.7K views9 slides
Erlang introduction geek2geek Berlin by
Erlang introduction geek2geek BerlinErlang introduction geek2geek Berlin
Erlang introduction geek2geek BerlinPaolo Negri
1.4K views22 slides
Automate your docs, automate yourself by
Automate your docs, automate yourselfAutomate your docs, automate yourself
Automate your docs, automate yourselfChris Ward
335 views28 slides
The Anatomy of Content Management (workshop by J Gollner at Intelligent Conte... by
The Anatomy of Content Management (workshop by J Gollner at Intelligent Conte...The Anatomy of Content Management (workshop by J Gollner at Intelligent Conte...
The Anatomy of Content Management (workshop by J Gollner at Intelligent Conte...Joe Gollner
3.4K views34 slides

Viewers also liked(18)

Mongrel2, a short introduction by Paolo Negri
Mongrel2, a short introductionMongrel2, a short introduction
Mongrel2, a short introduction
Paolo Negri1.9K views
Offre développeur Javascript Back-end by Site Analyzer
Offre développeur Javascript Back-endOffre développeur Javascript Back-end
Offre développeur Javascript Back-end
Site Analyzer916 views
Contentful Berlin Offices by Irina Botea
Contentful Berlin OfficesContentful Berlin Offices
Contentful Berlin Offices
Irina Botea163.7K views
Erlang introduction geek2geek Berlin by Paolo Negri
Erlang introduction geek2geek BerlinErlang introduction geek2geek Berlin
Erlang introduction geek2geek Berlin
Paolo Negri1.4K views
Automate your docs, automate yourself by Chris Ward
Automate your docs, automate yourselfAutomate your docs, automate yourself
Automate your docs, automate yourself
Chris Ward335 views
The Anatomy of Content Management (workshop by J Gollner at Intelligent Conte... by Joe Gollner
The Anatomy of Content Management (workshop by J Gollner at Intelligent Conte...The Anatomy of Content Management (workshop by J Gollner at Intelligent Conte...
The Anatomy of Content Management (workshop by J Gollner at Intelligent Conte...
Joe Gollner3.4K views
AWS Lambda in infrastructure by Paolo Negri
AWS Lambda in infrastructureAWS Lambda in infrastructure
AWS Lambda in infrastructure
Paolo Negri2.2K views
Le futur de Drupal et des applications web by Julien Dubreuil
Le futur de Drupal et des applications webLe futur de Drupal et des applications web
Le futur de Drupal et des applications web
Julien Dubreuil4.7K views
Distributed and concurrent programming with RabbitMQ and EventMachine Rails U... by Paolo Negri
Distributed and concurrent programming with RabbitMQ and EventMachine Rails U...Distributed and concurrent programming with RabbitMQ and EventMachine Rails U...
Distributed and concurrent programming with RabbitMQ and EventMachine Rails U...
Paolo Negri6.6K views
Devoxx France 2015 - Se préparer à l'arrivée d'Angular 2 by Romain Linsolas
Devoxx France 2015 - Se préparer à l'arrivée d'Angular 2Devoxx France 2015 - Se préparer à l'arrivée d'Angular 2
Devoxx France 2015 - Se préparer à l'arrivée d'Angular 2
Romain Linsolas7K views
Back to the future with static site generators by Chris Ward
Back to the future with static site generatorsBack to the future with static site generators
Back to the future with static site generators
Chris Ward449 views
ParisJS #10 : PhantomJs by Maurice Svay
ParisJS #10 : PhantomJs ParisJS #10 : PhantomJs
ParisJS #10 : PhantomJs
Maurice Svay12.4K views
Erlang as a cloud citizen, a fractal approach to throughput by Paolo Negri
Erlang as a cloud citizen, a fractal approach to throughputErlang as a cloud citizen, a fractal approach to throughput
Erlang as a cloud citizen, a fractal approach to throughput
Paolo Negri1.4K views
Google : Prise en charge de l'Ajax et de l'Angular JS by Peak Ace
Google : Prise en charge de l'Ajax et de l'Angular JSGoogle : Prise en charge de l'Ajax et de l'Angular JS
Google : Prise en charge de l'Ajax et de l'Angular JS
Peak Ace1.5K views
API Days Australia - Automatic Testing of (RESTful) API Documentation by Rouven Weßling
API Days Australia  - Automatic Testing of (RESTful) API DocumentationAPI Days Australia  - Automatic Testing of (RESTful) API Documentation
API Days Australia - Automatic Testing of (RESTful) API Documentation
Rouven Weßling607 views

Similar to A Documentation Crash Course, LinuxCon 2016

EDS for JIBS by
EDS for JIBSEDS for JIBS
EDS for JIBSCliveRWright
637 views51 slides
Agile Localization: Oxymoron or Heroic Achievement? by
Agile Localization: Oxymoron or Heroic Achievement?Agile Localization: Oxymoron or Heroic Achievement?
Agile Localization: Oxymoron or Heroic Achievement?Laura Dent
160 views32 slides
Scientific and technical translation in English - Week 8 by
Scientific and technical translation in English - Week 8Scientific and technical translation in English - Week 8
Scientific and technical translation in English - Week 8Ron Martinez
1.9K views51 slides
Natural language processing and search by
Natural language processing and searchNatural language processing and search
Natural language processing and searchNathan McMinn
384 views39 slides
LF_APIStrat17_Don't Repeat Yourself - Your API is Your Documentation by
LF_APIStrat17_Don't Repeat Yourself - Your API is Your DocumentationLF_APIStrat17_Don't Repeat Yourself - Your API is Your Documentation
LF_APIStrat17_Don't Repeat Yourself - Your API is Your DocumentationLF_APIStrat
40 views30 slides
Untangling6 by
Untangling6Untangling6
Untangling6Derek Jacoby
434 views23 slides

Similar to A Documentation Crash Course, LinuxCon 2016(20)

Agile Localization: Oxymoron or Heroic Achievement? by Laura Dent
Agile Localization: Oxymoron or Heroic Achievement?Agile Localization: Oxymoron or Heroic Achievement?
Agile Localization: Oxymoron or Heroic Achievement?
Laura Dent160 views
Scientific and technical translation in English - Week 8 by Ron Martinez
Scientific and technical translation in English - Week 8Scientific and technical translation in English - Week 8
Scientific and technical translation in English - Week 8
Ron Martinez1.9K views
Natural language processing and search by Nathan McMinn
Natural language processing and searchNatural language processing and search
Natural language processing and search
Nathan McMinn384 views
LF_APIStrat17_Don't Repeat Yourself - Your API is Your Documentation by LF_APIStrat
LF_APIStrat17_Don't Repeat Yourself - Your API is Your DocumentationLF_APIStrat17_Don't Repeat Yourself - Your API is Your Documentation
LF_APIStrat17_Don't Repeat Yourself - Your API is Your Documentation
LF_APIStrat40 views
"Done" - Are We There Yet? by Paul Rayner
"Done" - Are We There Yet?"Done" - Are We There Yet?
"Done" - Are We There Yet?
Paul Rayner991 views
Data Science Salon: In your own words: computing customer similarity from tex... by Formulatedby
Data Science Salon: In your own words: computing customer similarity from tex...Data Science Salon: In your own words: computing customer similarity from tex...
Data Science Salon: In your own words: computing customer similarity from tex...
Formulatedby286 views
The Agile UX Equation: How to Implement UserZoom Within Your Agile Framework by UserZoom
The Agile UX Equation: How to Implement UserZoom Within Your Agile FrameworkThe Agile UX Equation: How to Implement UserZoom Within Your Agile Framework
The Agile UX Equation: How to Implement UserZoom Within Your Agile Framework
UserZoom294 views
Natural Language Processing for Data Analytics - Tel Aviv Summit 2018 by Amazon Web Services
Natural Language Processing for Data Analytics - Tel Aviv Summit 2018Natural Language Processing for Data Analytics - Tel Aviv Summit 2018
Natural Language Processing for Data Analytics - Tel Aviv Summit 2018
On Readability of Code by Arun Saha
On Readability of CodeOn Readability of Code
On Readability of Code
Arun Saha667 views
My research experience and some useful adademic material and tips by wangxg
My research experience and some useful adademic material and tipsMy research experience and some useful adademic material and tips
My research experience and some useful adademic material and tips
wangxg967 views
Statistical Entity Linking by PyDataParis
Statistical Entity LinkingStatistical Entity Linking
Statistical Entity Linking
PyDataParis41 views
Docs as-code-missing.-manual by Margaret Eker
Docs as-code-missing.-manualDocs as-code-missing.-manual
Docs as-code-missing.-manual
Margaret Eker1.5K views
Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, ... by Tom Hofte
Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, ...Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, ...
Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, ...
Tom Hofte2.8K views
It's XP Stupid (2019) by Mike Harris
It's XP Stupid (2019)It's XP Stupid (2019)
It's XP Stupid (2019)
Mike Harris36 views

More from Chris Ward

Building Cross Platform Apps with Electron by
Building Cross Platform Apps with ElectronBuilding Cross Platform Apps with Electron
Building Cross Platform Apps with ElectronChris Ward
435 views14 slides
Android Programming without Java by
Android Programming without JavaAndroid Programming without Java
Android Programming without JavaChris Ward
247 views18 slides
The past, present and future of swift, Voxxed Belgrade 2016 by
The past, present and future of swift, Voxxed Belgrade 2016The past, present and future of swift, Voxxed Belgrade 2016
The past, present and future of swift, Voxxed Belgrade 2016Chris Ward
235 views41 slides
Always Listening User Experience by
Always Listening User ExperienceAlways Listening User Experience
Always Listening User ExperienceChris Ward
541 views25 slides
JS, CMS, untangle the mess by
JS, CMS, untangle the messJS, CMS, untangle the mess
JS, CMS, untangle the messChris Ward
3.4K views30 slides
Extend Drupal with a CRM, DrupalGov 2013 by
Extend Drupal with a CRM, DrupalGov 2013Extend Drupal with a CRM, DrupalGov 2013
Extend Drupal with a CRM, DrupalGov 2013Chris Ward
890 views24 slides

More from Chris Ward(20)

Building Cross Platform Apps with Electron by Chris Ward
Building Cross Platform Apps with ElectronBuilding Cross Platform Apps with Electron
Building Cross Platform Apps with Electron
Chris Ward435 views
Android Programming without Java by Chris Ward
Android Programming without JavaAndroid Programming without Java
Android Programming without Java
Chris Ward247 views
The past, present and future of swift, Voxxed Belgrade 2016 by Chris Ward
The past, present and future of swift, Voxxed Belgrade 2016The past, present and future of swift, Voxxed Belgrade 2016
The past, present and future of swift, Voxxed Belgrade 2016
Chris Ward235 views
Always Listening User Experience by Chris Ward
Always Listening User ExperienceAlways Listening User Experience
Always Listening User Experience
Chris Ward541 views
JS, CMS, untangle the mess by Chris Ward
JS, CMS, untangle the messJS, CMS, untangle the mess
JS, CMS, untangle the mess
Chris Ward3.4K views
Extend Drupal with a CRM, DrupalGov 2013 by Chris Ward
Extend Drupal with a CRM, DrupalGov 2013Extend Drupal with a CRM, DrupalGov 2013
Extend Drupal with a CRM, DrupalGov 2013
Chris Ward890 views
Drupal DevOps - Melbourne DevOps July 2013 by Chris Ward
Drupal DevOps - Melbourne DevOps July 2013Drupal DevOps - Melbourne DevOps July 2013
Drupal DevOps - Melbourne DevOps July 2013
Chris Ward1.7K views
Removing Barriers in Engagement - Melbourne Geek Night, July 2013 by Chris Ward
Removing Barriers in Engagement - Melbourne Geek Night, July 2013Removing Barriers in Engagement - Melbourne Geek Night, July 2013
Removing Barriers in Engagement - Melbourne Geek Night, July 2013
Chris Ward750 views
Power your mobile app with Drupal - Melbourne Mobile, July 2013 by Chris Ward
Power your mobile app with Drupal - Melbourne Mobile, July 2013Power your mobile app with Drupal - Melbourne Mobile, July 2013
Power your mobile app with Drupal - Melbourne Mobile, July 2013
Chris Ward2.5K views
Tweak, Test and Debug your mobile apps from Web directions code 13 by Chris Ward
Tweak, Test and Debug your mobile apps from Web directions code 13Tweak, Test and Debug your mobile apps from Web directions code 13
Tweak, Test and Debug your mobile apps from Web directions code 13
Chris Ward983 views
Why your image of the world could be wrong by Chris Ward
Why your image of the world could be wrongWhy your image of the world could be wrong
Why your image of the world could be wrong
Chris Ward1.6K views
Take your drupal sites offline by Chris Ward
Take your drupal sites offlineTake your drupal sites offline
Take your drupal sites offline
Chris Ward4.2K views
Green Renters' Giant Green Games by Chris Ward
Green Renters' Giant Green GamesGreen Renters' Giant Green Games
Green Renters' Giant Green Games
Chris Ward253 views
Customising civicrm by Chris Ward
Customising civicrmCustomising civicrm
Customising civicrm
Chris Ward2.3K views
Drupal - Melbourne cryptoparty by Chris Ward
Drupal - Melbourne cryptopartyDrupal - Melbourne cryptoparty
Drupal - Melbourne cryptoparty
Chris Ward505 views
HP Lovecraft, laneway learning by Chris Ward
HP Lovecraft, laneway learningHP Lovecraft, laneway learning
HP Lovecraft, laneway learning
Chris Ward2.8K views
CiviCRM and Wordpress by Chris Ward
CiviCRM and WordpressCiviCRM and Wordpress
CiviCRM and Wordpress
Chris Ward781 views
Blogging with drupal by Chris Ward
Blogging with drupalBlogging with drupal
Blogging with drupal
Chris Ward718 views
Building mobile apps with PhoneGap and Titanium appcelerator by Chris Ward
Building mobile apps with PhoneGap and Titanium appceleratorBuilding mobile apps with PhoneGap and Titanium appcelerator
Building mobile apps with PhoneGap and Titanium appcelerator
Chris Ward805 views
Jquery mobile by Chris Ward
Jquery mobileJquery mobile
Jquery mobile
Chris Ward1.1K views

Recently uploaded

Java Platform Approach 1.0 - Picnic Meetup by
Java Platform Approach 1.0 - Picnic MeetupJava Platform Approach 1.0 - Picnic Meetup
Java Platform Approach 1.0 - Picnic MeetupRick Ossendrijver
25 views39 slides
The Importance of Cybersecurity for Digital Transformation by
The Importance of Cybersecurity for Digital TransformationThe Importance of Cybersecurity for Digital Transformation
The Importance of Cybersecurity for Digital TransformationNUS-ISS
25 views26 slides
How the World's Leading Independent Automotive Distributor is Reinventing Its... by
How the World's Leading Independent Automotive Distributor is Reinventing Its...How the World's Leading Independent Automotive Distributor is Reinventing Its...
How the World's Leading Independent Automotive Distributor is Reinventing Its...NUS-ISS
15 views25 slides
Roadmap to Become Experts.pptx by
Roadmap to Become Experts.pptxRoadmap to Become Experts.pptx
Roadmap to Become Experts.pptxdscwidyatamanew
11 views45 slides
.conf Go 2023 - How KPN drives Customer Satisfaction on IPTV by
.conf Go 2023 - How KPN drives Customer Satisfaction on IPTV.conf Go 2023 - How KPN drives Customer Satisfaction on IPTV
.conf Go 2023 - How KPN drives Customer Satisfaction on IPTVSplunk
86 views20 slides
RADIUS-Omnichannel Interaction System by
RADIUS-Omnichannel Interaction SystemRADIUS-Omnichannel Interaction System
RADIUS-Omnichannel Interaction SystemRADIUS
14 views21 slides

Recently uploaded(20)

The Importance of Cybersecurity for Digital Transformation by NUS-ISS
The Importance of Cybersecurity for Digital TransformationThe Importance of Cybersecurity for Digital Transformation
The Importance of Cybersecurity for Digital Transformation
NUS-ISS25 views
How the World's Leading Independent Automotive Distributor is Reinventing Its... by NUS-ISS
How the World's Leading Independent Automotive Distributor is Reinventing Its...How the World's Leading Independent Automotive Distributor is Reinventing Its...
How the World's Leading Independent Automotive Distributor is Reinventing Its...
NUS-ISS15 views
.conf Go 2023 - How KPN drives Customer Satisfaction on IPTV by Splunk
.conf Go 2023 - How KPN drives Customer Satisfaction on IPTV.conf Go 2023 - How KPN drives Customer Satisfaction on IPTV
.conf Go 2023 - How KPN drives Customer Satisfaction on IPTV
Splunk86 views
RADIUS-Omnichannel Interaction System by RADIUS
RADIUS-Omnichannel Interaction SystemRADIUS-Omnichannel Interaction System
RADIUS-Omnichannel Interaction System
RADIUS14 views
Igniting Next Level Productivity with AI-Infused Data Integration Workflows by Safe Software
Igniting Next Level Productivity with AI-Infused Data Integration Workflows Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Safe Software91 views
DALI Basics Course 2023 by Ivory Egg
DALI Basics Course  2023DALI Basics Course  2023
DALI Basics Course 2023
Ivory Egg14 views
Perth MeetUp November 2023 by Michael Price
Perth MeetUp November 2023 Perth MeetUp November 2023
Perth MeetUp November 2023
Michael Price12 views
Empathic Computing: Delivering the Potential of the Metaverse by Mark Billinghurst
Empathic Computing: Delivering  the Potential of the MetaverseEmpathic Computing: Delivering  the Potential of the Metaverse
Empathic Computing: Delivering the Potential of the Metaverse
Mark Billinghurst449 views
[2023] Putting the R! in R&D.pdf by Eleanor McHugh
[2023] Putting the R! in R&D.pdf[2023] Putting the R! in R&D.pdf
[2023] Putting the R! in R&D.pdf
Eleanor McHugh38 views
STPI OctaNE CoE Brochure.pdf by madhurjyapb
STPI OctaNE CoE Brochure.pdfSTPI OctaNE CoE Brochure.pdf
STPI OctaNE CoE Brochure.pdf
madhurjyapb12 views
Transcript: The Details of Description Techniques tips and tangents on altern... by BookNet Canada
Transcript: The Details of Description Techniques tips and tangents on altern...Transcript: The Details of Description Techniques tips and tangents on altern...
Transcript: The Details of Description Techniques tips and tangents on altern...
BookNet Canada119 views
SAP Automation Using Bar Code and FIORI.pdf by Virendra Rai, PMP
SAP Automation Using Bar Code and FIORI.pdfSAP Automation Using Bar Code and FIORI.pdf
SAP Automation Using Bar Code and FIORI.pdf
Future of Learning - Khoong Chan Meng by NUS-ISS
Future of Learning - Khoong Chan MengFuture of Learning - Khoong Chan Meng
Future of Learning - Khoong Chan Meng
NUS-ISS31 views
Voice Logger - Telephony Integration Solution at Aegis by Nirmal Sharma
Voice Logger - Telephony Integration Solution at AegisVoice Logger - Telephony Integration Solution at Aegis
Voice Logger - Telephony Integration Solution at Aegis
Nirmal Sharma17 views

A Documentation Crash Course, LinuxCon 2016