Click here to Skip to main content
15,916,693 members

Survey Results

What makes great documentation?

Survey period: 12 Aug 2019 to 19 Aug 2019

Great docs can convince us to use a product. Bad docs just make our lives painful.

OptionVotes% 
It contains code samples50872.78
It includes step-by-step instructions to complete specific tasks42460.74
It provides information targeted towards novice users33648.14
It provides information targeted towards advanced users30643.84
It includes a walk-through of a sample application31745.42
It lists common API calls31845.56
Is comprehensive and covers every possible scenario (within reason)19828.37
It provides a quick overview of the key points in the documentation39857.02
Other (please comment)486.88
Respondents were allowed to choose more than one answer; totals may not add up to 100%

View optional text answers (49 answers)


 
GeneralConsidering the audience, part 2 Pin
Gary R. Wheeler16-Aug-19 14:31
Gary R. Wheeler16-Aug-19 14:31 
GeneralProvides an outside-in view Pin
Amarnath S14-Aug-19 5:02
professionalAmarnath S14-Aug-19 5:02 
GeneralAll of the Above Pin
Sammuel Miranda13-Aug-19 8:47
professionalSammuel Miranda13-Aug-19 8:47 
GeneralIt draws "the big picture", showing the architecture - how pieces fit together Pin
kalberts13-Aug-19 1:02
kalberts13-Aug-19 1:02 
GeneralRe: It draws "the big picture", showing the architecture - how pieces fit together Pin
MikeTheFid13-Aug-19 4:45
MikeTheFid13-Aug-19 4:45 
GeneralIt exists Pin
kalberts13-Aug-19 0:43
kalberts13-Aug-19 0:43 
GeneralRe: It exists Pin
Chris Maunder13-Aug-19 3:18
cofounderChris Maunder13-Aug-19 3:18 
GeneralDepends on the audience Pin
CHill6012-Aug-19 23:13
mveCHill6012-Aug-19 23:13 
GeneralRe: Depends on the audience Pin
Chris Maunder13-Aug-19 3:17
cofounderChris Maunder13-Aug-19 3:17 
GeneralRe: Depends on the audience Pin
Rick York13-Aug-19 13:25
mveRick York13-Aug-19 13:25 
GeneralRe: Depends on the audience Pin
CHill6014-Aug-19 0:46
mveCHill6014-Aug-19 0:46 
If it's documentation for software developers then yes - must include code samples.

By "users" I mean "business users" - the non-technical staff that use the software we produce.

So the "application" that I've inherited to support has "technical docs" intended to show a programmer how it works, standing data that needs to be maintained, known issues etc. A subset of that is intended for the Change Management Team and describes how to promote upgrades into production.

The "business documentation" is intended to show an office worker (aka "user") how to use the application - "Enter your client code here and press this button" type of thing.

Clear as mud now Laugh | :laugh:
GeneralIt's 2019. I m looking for video/gif/screen shots in example Pin
Anurag Gandhi12-Aug-19 8:55
professionalAnurag Gandhi12-Aug-19 8:55 
GeneralRe: It's 2019. I m looking for video/gif/screen shots in example Pin
CHill6012-Aug-19 23:11
mveCHill6012-Aug-19 23:11 
GeneralRe: It's 2019. I m looking for video/gif/screen shots in example Pin
jackbrownii13-Aug-19 5:22
professionaljackbrownii13-Aug-19 5:22 
GeneralRe: It's 2019. I m looking for video/gif/screen shots in example Pin
Marc Clifton13-Aug-19 8:06
mvaMarc Clifton13-Aug-19 8:06 
GeneralRe: It's 2019. I m looking for video/gif/screen shots in example Pin
kalberts13-Aug-19 20:42
kalberts13-Aug-19 20:42 
AnswerOther - Overview of what the application/framework/library is able to do. Pin
Member 1125611712-Aug-19 7:46
Member 1125611712-Aug-19 7:46 
GeneralOrganized, easily searchable, indexed, table of contents, reference links, UP TO DATE, and I can add my own comments! Pin
Marc Clifton12-Aug-19 3:03
mvaMarc Clifton12-Aug-19 3:03 
GeneralRe: Organized, easily searchable, indexed, table of contents, reference links, UP TO DATE, and I can add my own comments! Pin
kalberts13-Aug-19 1:16
kalberts13-Aug-19 1:16 
GeneralThe Premise is wrong Pin
#realJSOP11-Aug-19 23:22
professional#realJSOP11-Aug-19 23:22 
PraiseRe: The Premise is wrong Pin
Slacker00712-Aug-19 1:08
professionalSlacker00712-Aug-19 1:08 
GeneralRe: The Premise is wrong Pin
Ryan Peden12-Aug-19 3:03
professionalRyan Peden12-Aug-19 3:03 
GeneralRe: The Premise is wrong Pin
Chris Maunder12-Aug-19 3:05
cofounderChris Maunder12-Aug-19 3:05 
GeneralRe: The Premise is wrong Pin
#realJSOP12-Aug-19 3:16
professional#realJSOP12-Aug-19 3:16 
GeneralRe: The Premise is wrong Pin
Chris Maunder13-Aug-19 3:30
cofounderChris Maunder13-Aug-19 3:30 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.