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 
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 
Every now and then you see really high quality instructional videos, often made by commercial intrests: I've got a small handful of videos showing you, step by step, how to cast a concrete floor, how to put up wall paper, how to install your new central vacuum cleaner. The instructors are not rushed, but there is no wasted time. Images are sharp and clear, closeup when needed, overview when more suitable. Divided into chapters corresponding to the work steps.

Such videos exist, but they are few and far between. Those craftsman videos were published on DVD; if you take that expense, you want to do a decent job.

The vast majority of "instructional" videos on YouTube bear no sign of professionality, neither in the instructional contents nor in the video quality; they often look as if they are made by the teenager next door who are testing out the video functionality of his new smarphone. Some are made by a manufacturer, using "instructions" as a poor disguise for advertising: The essential thing is to show how great his product is, and how you can extend it with plugins bought at a very favorable price.

And then there are those - both as videos, plain web pages and printed books - that says "Don't worry, just do these steps one by one to solve your task - you don't have to understand a thing, if you just know what to do". These are the ones that really offend me the most. I feel that I am not being taken seriously as a learner, as a user. I have had too many own experiences where it took me a long time to get beyond the very most elementary level because noone was able to make me understand the inner workings.

And, nowadays I more or less have to hold back my colleagues, forcing them to listen to an explanation of how things work - they insist on me just telling them what to do. No, I say - then you will be back in a few days with another problem you are unable to solve because you did't understand how it works. Listen to me, and you can handle the next problem yourself! ... This is far more expressed with young people; they are far less willing to "waste" the time om obtaining any deeper understanding. So they are far more satisfied with those cursory explanations that solves the immediate problem, and that is it. Deeper understanding is for oldtimers, it seems.
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.