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 
CHill60 has a good start below; let's expand on it a bit. He says you have to "consider your audience". Based on Chris M's comments elsewhere in the forum, that audience is us: developers. The product being documented is a software package or application that the software we develop is going to interact with in some way.

I put to you that the purpose of all product documentation is the same: answer the questions that the product itself does not answer by its very nature. We now need to figure out two things: what are the questions developers are likely to ask, and how should we frame the answers?

When you 'consider the audience', you should realize first and foremost that the developer is using your product to solve a problem or meet a requirement in his own task. Your product is not an end in and of itself. What are the problems he's trying to solve? What are the forms his solutions are likely to take? Remember that, while you may have the hottest hyper-fulcrum-folding-widget in town, all he cares is that he puts fulcrums in one end, and they come out neatly folded at the other. Just because he's another developer should you think he's going to be impressed by the fact that your fulcrum folding algorithm is based upon a neural network of free-form monads linked in a five-dimensional matrix of polytonic properties. He just wants his fulcrums folded, no muss, no fuss.

Knowing the questions will often suggest at least the form the answers take:
  • "What's a fulcrum, and why do I need to fold it? My boss says I've got to have this done by the weekend." - Here's an introduction on fulcrums, plus a tutorial for doing basic folding using our product.
  • "What's the API?" - reference documentation plus complete working samples that use most, if not all, of the API.
  • "How do I create fulcrums that your widget can handle?" - Define your fulcrum format, give them a library that produces validated fulcrums (fulcra?) from basic input. Maybe fulcrums have an ANSI standard representation, parts of which are optional. Tell them which options you support, which ones you don't, and why.
  • "I need to multithread my fulcrum folding with my retrograde spinnaker production. How do I do that?" - If that's a common thing, give them a sample that at least shows the highlights.
All of these statements have the same intent. In order to have good product documentation, you must have the ability to place yourself in that documentation consumer's shoes and address his needs. We as developers love simple solutions to this problem, which explains why doxygen and similar products get so much traction. Unfortunately those products only work when used to create reference documents. All too often we developers have to make do with this kind of documentation, along with the source for one or two brief sample programs.

TL;DR: It depends. Laugh | :laugh:
Software Zen: delete this;

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 
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.