SlideShare ist ein Scribd-Unternehmen logo
1 von 57
Creating Beautiful Open Source  Technical Documentation Or:  Writing FOSS  Docs that  Don't Suck
 
 
Technical Writing A Fairy Tale
A long time ago in a galaxy far  far away ...
Jane
Fred Sue Bob
Monday
Tuesday
Tuesday My l337 db rawks!
Wednesday
Wednesday My h4X0r skills are teh win!
Thursday
Thursday My design skillz are made of awesome!
Friday
Friday WTF?!
Friday
Friday My l337 db rawks!
Friday My h4X0r skills are teh win!
Friday All users base are belong to us
Friday
Saturday
Sunday
Monday Ship it!
Tuesday
Wednesday
Thursday
Thursday ???
Thursday !!!
Thursday $*!%
Friday Dole queue
Just because you can READ a manual ...
Doesn't mean you can write one.
Happily Ever After?
Information Plan Content Specification Writing Translation & Production Review Release 5 Phase Model by JoAnn Hackos
“ A common mistake that people make when trying to design something completely foolproof  is to underestimate the ingenuity of complete fools ” Douglas Adams “Mostly Harmless”
 
 
 
 
 
How To: Write FOSS Docs that don't suck
no one reads manuals! But ...
Why Document?
What makes your  software  awesome?
These things all work the same for documentation
Learnability
Efficiency
Retention
Few user errors
Satisfaction
It's all about the user
Whoever they might be
When users love the software then that's great software!
But when they don't ... the documentation should be there to save you
Beautiful documentation won't make crappy software any better But it might prevent some users  from trying to stab you
Lana Brindley Red Hat Technical Writer [email_address] +61 410 500 659 @Loquacities http://lanabrindley.blogspot.com/

Weitere Àhnliche Inhalte

Andere mochten auch

Documenting Business Processes
Documenting Business ProcessesDocumenting Business Processes
Documenting Business Processes
Rachel Houghton
 
Incorporating Visual Communication in Technical Documentation, for Usability!
Incorporating Visual Communication in Technical Documentation, for Usability!Incorporating Visual Communication in Technical Documentation, for Usability!
Incorporating Visual Communication in Technical Documentation, for Usability!
kate k
 

Andere mochten auch (20)

Best Practices for Documenting Technical Procedures
Best Practices for Documenting Technical ProceduresBest Practices for Documenting Technical Procedures
Best Practices for Documenting Technical Procedures
 
Guidelines for technical writing documents
Guidelines for technical writing documentsGuidelines for technical writing documents
Guidelines for technical writing documents
 
Documenting Business Processes
Documenting Business ProcessesDocumenting Business Processes
Documenting Business Processes
 
Best Practices for Writing and Editing User/Instruction Manuals
Best Practices for Writing and Editing User/Instruction ManualsBest Practices for Writing and Editing User/Instruction Manuals
Best Practices for Writing and Editing User/Instruction Manuals
 
The Accidental Writer: Great Web Copy for Everyone
The Accidental Writer: Great Web Copy for EveryoneThe Accidental Writer: Great Web Copy for Everyone
The Accidental Writer: Great Web Copy for Everyone
 
CAD MBD & 3D Technical Documentation
CAD MBD & 3D Technical DocumentationCAD MBD & 3D Technical Documentation
CAD MBD & 3D Technical Documentation
 
Augmenting your Technical Documentation with User-Generated Content
Augmenting your Technical Documentation with User-Generated ContentAugmenting your Technical Documentation with User-Generated Content
Augmenting your Technical Documentation with User-Generated Content
 
MediaWiki Quick Start Guide
MediaWiki Quick Start GuideMediaWiki Quick Start Guide
MediaWiki Quick Start Guide
 
Incorporating Visual Communication in Technical Documentation, for Usability!
Incorporating Visual Communication in Technical Documentation, for Usability!Incorporating Visual Communication in Technical Documentation, for Usability!
Incorporating Visual Communication in Technical Documentation, for Usability!
 
Technical Documentation Solutions
Technical Documentation SolutionsTechnical Documentation Solutions
Technical Documentation Solutions
 
Technical documentation and visual clues
Technical documentation and visual cluesTechnical documentation and visual clues
Technical documentation and visual clues
 
Monika Konieczny - Gamification & storytelling: how to turn boring technical ...
Monika Konieczny - Gamification & storytelling: how to turn boring technical ...Monika Konieczny - Gamification & storytelling: how to turn boring technical ...
Monika Konieczny - Gamification & storytelling: how to turn boring technical ...
 
Terminology Management Best Practices
Terminology Management Best PracticesTerminology Management Best Practices
Terminology Management Best Practices
 
MSTP
MSTPMSTP
MSTP
 
Achim Steinacker: Technical Documentation in the age of Industry 4.0
Achim Steinacker: Technical Documentation in the age of Industry 4.0Achim Steinacker: Technical Documentation in the age of Industry 4.0
Achim Steinacker: Technical Documentation in the age of Industry 4.0
 
Passing the baton: trusting students with the co-creation and ownership of OE...
Passing the baton: trusting students with the co-creation and ownership of OE...Passing the baton: trusting students with the co-creation and ownership of OE...
Passing the baton: trusting students with the co-creation and ownership of OE...
 
Technical Documentation *Passing the baton*
Technical Documentation *Passing the baton*Technical Documentation *Passing the baton*
Technical Documentation *Passing the baton*
 
Internet Of Things
Internet Of ThingsInternet Of Things
Internet Of Things
 
IoT Breakfast - AWS Amazon Web Services - Internet of Things
IoT Breakfast - AWS Amazon Web Services - Internet of ThingsIoT Breakfast - AWS Amazon Web Services - Internet of Things
IoT Breakfast - AWS Amazon Web Services - Internet of Things
 
Plan lector paco yunque
Plan lector paco yunquePlan lector paco yunque
Plan lector paco yunque
 

Ähnlich wie Writing Beautiful Technical Documentation

Culture And Aesthetic Revisited
Culture And Aesthetic RevisitedCulture And Aesthetic Revisited
Culture And Aesthetic Revisited
Adam Keys
 
Give a Great Tech Talk
Give a Great Tech TalkGive a Great Tech Talk
Give a Great Tech Talk
jberkus
 
Scottish Ruby Conference 2014
Scottish Ruby Conference  2014Scottish Ruby Conference  2014
Scottish Ruby Conference 2014
michaelag1971
 
Going Pro
Going ProGoing Pro
Going Pro
mlosee222
 
Five Stages of Development - Nordic.js
Five Stages of Development  - Nordic.jsFive Stages of Development  - Nordic.js
Five Stages of Development - Nordic.js
Robert Nyman
 
Making an Impact: UX Team of One
Making an Impact: UX Team of OneMaking an Impact: UX Team of One
Making an Impact: UX Team of One
vmcagwin
 

Ähnlich wie Writing Beautiful Technical Documentation (20)

Culture And Aesthetic Revisited
Culture And Aesthetic RevisitedCulture And Aesthetic Revisited
Culture And Aesthetic Revisited
 
Give a Great Tech Talk
Give a Great Tech TalkGive a Great Tech Talk
Give a Great Tech Talk
 
Scottish Ruby Conference 2014
Scottish Ruby Conference  2014Scottish Ruby Conference  2014
Scottish Ruby Conference 2014
 
How to get a Job as a Front End Developer
How to get a Job as a Front End DeveloperHow to get a Job as a Front End Developer
How to get a Job as a Front End Developer
 
Mobile Knife Fighting at JSConf US
Mobile Knife Fighting at JSConf US Mobile Knife Fighting at JSConf US
Mobile Knife Fighting at JSConf US
 
PSU Guest Lecture: Database Programming
PSU Guest Lecture: Database ProgrammingPSU Guest Lecture: Database Programming
PSU Guest Lecture: Database Programming
 
Going Pro
Going ProGoing Pro
Going Pro
 
Five Stages of Development - Nordic.js
Five Stages of Development  - Nordic.jsFive Stages of Development  - Nordic.js
Five Stages of Development - Nordic.js
 
Living Documentation (presentation)
Living Documentation (presentation)Living Documentation (presentation)
Living Documentation (presentation)
 
Developing The Web
Developing The WebDeveloping The Web
Developing The Web
 
From dev to ops and beyond - getting it done
From dev to ops and beyond - getting it doneFrom dev to ops and beyond - getting it done
From dev to ops and beyond - getting it done
 
Making an Impact: UX Team of One
Making an Impact: UX Team of OneMaking an Impact: UX Team of One
Making an Impact: UX Team of One
 
Even internet computers want to be free: Using Linux and open source software...
Even internet computers want to be free: Using Linux and open source software...Even internet computers want to be free: Using Linux and open source software...
Even internet computers want to be free: Using Linux and open source software...
 
Documentation for developers
Documentation for developersDocumentation for developers
Documentation for developers
 
Getting started programming on Linux
Getting started programming on LinuxGetting started programming on Linux
Getting started programming on Linux
 
What is a "programmer"?
What is a "programmer"?What is a "programmer"?
What is a "programmer"?
 
Build your own Language - Why and How?
Build your own Language - Why and How?Build your own Language - Why and How?
Build your own Language - Why and How?
 
Software Debugging for High-altitude Balloons
Software Debugging for High-altitude BalloonsSoftware Debugging for High-altitude Balloons
Software Debugging for High-altitude Balloons
 
Fitc Amsterdam 2010
Fitc Amsterdam 2010Fitc Amsterdam 2010
Fitc Amsterdam 2010
 
The myth of the small script
The myth of the small scriptThe myth of the small script
The myth of the small script
 

Mehr von Lana Brindley

Mehr von Lana Brindley (10)

Open Source Docs: The Good, The Bad, and the WTF?!
Open Source Docs: The Good, The Bad, and the WTF?!Open Source Docs: The Good, The Bad, and the WTF?!
Open Source Docs: The Good, The Bad, and the WTF?!
 
Open Source Documentation in Four Easy Steps (and one slightly more difficult...
Open Source Documentation in Four Easy Steps (and one slightly more difficult...Open Source Documentation in Four Easy Steps (and one slightly more difficult...
Open Source Documentation in Four Easy Steps (and one slightly more difficult...
 
The Grass is Greener on the Open Side
The Grass is Greener on the Open SideThe Grass is Greener on the Open Side
The Grass is Greener on the Open Side
 
Confessions of a Technical Writer
Confessions of a Technical WriterConfessions of a Technical Writer
Confessions of a Technical Writer
 
Technical Writing for Hoopy Open Source Froods Who Really Know Where Their To...
Technical Writing for Hoopy Open Source Froods Who Really Know Where Their To...Technical Writing for Hoopy Open Source Froods Who Really Know Where Their To...
Technical Writing for Hoopy Open Source Froods Who Really Know Where Their To...
 
Think It. Make It. Change the World.
Think It. Make It. Change the World.Think It. Make It. Change the World.
Think It. Make It. Change the World.
 
Getting Women into Open Source - The Easy Way
Getting Women into Open Source - The Easy WayGetting Women into Open Source - The Easy Way
Getting Women into Open Source - The Easy Way
 
Getting started With Linux: how NOT to do it.
Getting started With Linux: how NOT to do it.Getting started With Linux: how NOT to do it.
Getting started With Linux: how NOT to do it.
 
Technical writing: A fairy tale
Technical writing: A fairy taleTechnical writing: A fairy tale
Technical writing: A fairy tale
 
10 Reasons why you should not install Linux. Ever
10 Reasons why you should not install Linux. Ever10 Reasons why you should not install Linux. Ever
10 Reasons why you should not install Linux. Ever
 

KĂŒrzlich hochgeladen

+971581248768>> SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHA...
+971581248768>> SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHA...+971581248768>> SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHA...
+971581248768>> SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHA...
?#DUbAI#??##{{(☎+971_581248768%)**%*]'#abortion pills for sale in dubai@
 
Cloud Frontiers: A Deep Dive into Serverless Spatial Data and FME
Cloud Frontiers:  A Deep Dive into Serverless Spatial Data and FMECloud Frontiers:  A Deep Dive into Serverless Spatial Data and FME
Cloud Frontiers: A Deep Dive into Serverless Spatial Data and FME
Safe Software
 
Architecting Cloud Native Applications
Architecting Cloud Native ApplicationsArchitecting Cloud Native Applications
Architecting Cloud Native Applications
WSO2
 
Finding Java's Hidden Performance Traps @ DevoxxUK 2024
Finding Java's Hidden Performance Traps @ DevoxxUK 2024Finding Java's Hidden Performance Traps @ DevoxxUK 2024
Finding Java's Hidden Performance Traps @ DevoxxUK 2024
Victor Rentea
 

KĂŒrzlich hochgeladen (20)

Apidays New York 2024 - Passkeys: Developing APIs to enable passwordless auth...
Apidays New York 2024 - Passkeys: Developing APIs to enable passwordless auth...Apidays New York 2024 - Passkeys: Developing APIs to enable passwordless auth...
Apidays New York 2024 - Passkeys: Developing APIs to enable passwordless auth...
 
+971581248768>> SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHA...
+971581248768>> SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHA...+971581248768>> SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHA...
+971581248768>> SAFE AND ORIGINAL ABORTION PILLS FOR SALE IN DUBAI AND ABUDHA...
 
Strategies for Landing an Oracle DBA Job as a Fresher
Strategies for Landing an Oracle DBA Job as a FresherStrategies for Landing an Oracle DBA Job as a Fresher
Strategies for Landing an Oracle DBA Job as a Fresher
 
Apidays New York 2024 - The Good, the Bad and the Governed by David O'Neill, ...
Apidays New York 2024 - The Good, the Bad and the Governed by David O'Neill, ...Apidays New York 2024 - The Good, the Bad and the Governed by David O'Neill, ...
Apidays New York 2024 - The Good, the Bad and the Governed by David O'Neill, ...
 
TrustArc Webinar - Unlock the Power of AI-Driven Data Discovery
TrustArc Webinar - Unlock the Power of AI-Driven Data DiscoveryTrustArc Webinar - Unlock the Power of AI-Driven Data Discovery
TrustArc Webinar - Unlock the Power of AI-Driven Data Discovery
 
Apidays New York 2024 - APIs in 2030: The Risk of Technological Sleepwalk by ...
Apidays New York 2024 - APIs in 2030: The Risk of Technological Sleepwalk by ...Apidays New York 2024 - APIs in 2030: The Risk of Technological Sleepwalk by ...
Apidays New York 2024 - APIs in 2030: The Risk of Technological Sleepwalk by ...
 
AWS Community Day CPH - Three problems of Terraform
AWS Community Day CPH - Three problems of TerraformAWS Community Day CPH - Three problems of Terraform
AWS Community Day CPH - Three problems of Terraform
 
Polkadot JAM Slides - Token2049 - By Dr. Gavin Wood
Polkadot JAM Slides - Token2049 - By Dr. Gavin WoodPolkadot JAM Slides - Token2049 - By Dr. Gavin Wood
Polkadot JAM Slides - Token2049 - By Dr. Gavin Wood
 
Strategize a Smooth Tenant-to-tenant Migration and Copilot Takeoff
Strategize a Smooth Tenant-to-tenant Migration and Copilot TakeoffStrategize a Smooth Tenant-to-tenant Migration and Copilot Takeoff
Strategize a Smooth Tenant-to-tenant Migration and Copilot Takeoff
 
Cyberprint. Dark Pink Apt Group [EN].pdf
Cyberprint. Dark Pink Apt Group [EN].pdfCyberprint. Dark Pink Apt Group [EN].pdf
Cyberprint. Dark Pink Apt Group [EN].pdf
 
Navigating the Deluge_ Dubai Floods and the Resilience of Dubai International...
Navigating the Deluge_ Dubai Floods and the Resilience of Dubai International...Navigating the Deluge_ Dubai Floods and the Resilience of Dubai International...
Navigating the Deluge_ Dubai Floods and the Resilience of Dubai International...
 
Apidays New York 2024 - Accelerating FinTech Innovation by Vasa Krishnan, Fin...
Apidays New York 2024 - Accelerating FinTech Innovation by Vasa Krishnan, Fin...Apidays New York 2024 - Accelerating FinTech Innovation by Vasa Krishnan, Fin...
Apidays New York 2024 - Accelerating FinTech Innovation by Vasa Krishnan, Fin...
 
ProductAnonymous-April2024-WinProductDiscovery-MelissaKlemke
ProductAnonymous-April2024-WinProductDiscovery-MelissaKlemkeProductAnonymous-April2024-WinProductDiscovery-MelissaKlemke
ProductAnonymous-April2024-WinProductDiscovery-MelissaKlemke
 
Corporate and higher education May webinar.pptx
Corporate and higher education May webinar.pptxCorporate and higher education May webinar.pptx
Corporate and higher education May webinar.pptx
 
Connector Corner: Accelerate revenue generation using UiPath API-centric busi...
Connector Corner: Accelerate revenue generation using UiPath API-centric busi...Connector Corner: Accelerate revenue generation using UiPath API-centric busi...
Connector Corner: Accelerate revenue generation using UiPath API-centric busi...
 
Apidays New York 2024 - The value of a flexible API Management solution for O...
Apidays New York 2024 - The value of a flexible API Management solution for O...Apidays New York 2024 - The value of a flexible API Management solution for O...
Apidays New York 2024 - The value of a flexible API Management solution for O...
 
Cloud Frontiers: A Deep Dive into Serverless Spatial Data and FME
Cloud Frontiers:  A Deep Dive into Serverless Spatial Data and FMECloud Frontiers:  A Deep Dive into Serverless Spatial Data and FME
Cloud Frontiers: A Deep Dive into Serverless Spatial Data and FME
 
Architecting Cloud Native Applications
Architecting Cloud Native ApplicationsArchitecting Cloud Native Applications
Architecting Cloud Native Applications
 
Ransomware_Q4_2023. The report. [EN].pdf
Ransomware_Q4_2023. The report. [EN].pdfRansomware_Q4_2023. The report. [EN].pdf
Ransomware_Q4_2023. The report. [EN].pdf
 
Finding Java's Hidden Performance Traps @ DevoxxUK 2024
Finding Java's Hidden Performance Traps @ DevoxxUK 2024Finding Java's Hidden Performance Traps @ DevoxxUK 2024
Finding Java's Hidden Performance Traps @ DevoxxUK 2024
 

Writing Beautiful Technical Documentation