Click here to Skip to main content
15,916,835 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 PinPopular
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 PinPopular
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 PinPopular
#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 
It doesn't imply we're talking about an application at all. Let's go through each option one by one.
  1. It contains code samples

    The documentation contains code samples that help you integrate a component, or call a service, or make an API call, or make a PowerShell call. It provides a direct example of some type of coding.

  2. It includes step-by-step instructions to complete specific tasks

    This could be integrating a component, or authorising a user to call a service, or installing a system

  3. It provides information targeted towards novice users
  4. It provides information targeted towards advanced users

    This is applicable to pretty much anything related to documentation in IT.

  5. It includes a walk-through of a sample application

    This could be a Hello World app that includes a component, or integrates a back-end service. Maybe it's an Angular component and the docs include a sample app that walks you through everything from installing via npm through to deploying. Maybe it's an iOS service and there's a sample app that shows how to authenticate your users including network connectivity issues. The app isn't the product. The app is a sample included in the docs to show how to use the product in the real world.

  6. It lists common API calls
  7. Is comprehensive and covers every possible scenario (within reason)
  8. It provides a quick overview of the key points in the documentation

    I think these are self explanatory.
#realJSOP wrote:
There's no such thing as decent documentation

So tell us what would make deceny documentation.
cheers
Chris Maunder

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.