Click here to Skip to main content
15,918,889 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)


 
GeneralRe: The Premise is wrong Pin
Ravi Bhavnani13-Aug-19 15:38
professionalRavi Bhavnani13-Aug-19 15:38 
GeneralRe: The Premise is wrong Pin
Chris Maunder14-Aug-19 1:58
cofounderChris Maunder14-Aug-19 1:58 
GeneralRe: The Premise is wrong Pin
Ravi Bhavnani14-Aug-19 5:44
professionalRavi Bhavnani14-Aug-19 5:44 
GeneralRe: The Premise is wrong Pin
Ravi Bhavnani13-Aug-19 15:39
professionalRavi Bhavnani13-Aug-19 15:39 
GeneralRe: The Premise is wrong Pin
Sander Rossel12-Aug-19 21:48
professionalSander Rossel12-Aug-19 21:48 
GeneralRe: The Premise is wrong Pin
Ravi Bhavnani13-Aug-19 15:37
professionalRavi Bhavnani13-Aug-19 15:37 
GeneralRe: The Premise is wrong Pin
Sander Rossel13-Aug-19 19:55
professionalSander Rossel13-Aug-19 19:55 
GeneralRe: The Premise is wrong Pin
kalberts13-Aug-19 21:22
kalberts13-Aug-19 21:22 
All the time, you see programmers trying do defend the lack of comments in their code, arguing with silly examples of silly comments. It is like arguing that scientific dissertation have no value, "proven" by your eight year old's first essay assignment in school. Lots of the examples in your link of poor commenting are not "poor", but outright silly. Noone would be able to defend those comments. They are 100% invalid as arguments agains writing good, valuable comments.

I often pick up code that I haven't touched for a full year or two. Or, I take over the responsiblity of someone else's code, that I have never seen before. Even in my old code, I frequently hesitate: Now, why did I do that? Why is that test required here? That re-raising of the exception, why isn't it fully handled here?

Every time I don't immediately see the whys, I set out to find the answer. When I find it, it often leads to a new brief end-of-line comment (I am fond of those - nicely lined up from col.70 so they do not interfere too much with the plain code).

So, when I write new code, I try to ask myself which "whys" I will be asking myself a year from now (or some other coder may be asking a week from now), and add the end-of-line comment right away. Sometimes, I do not hit the nail on the head, and a year later I remove the comment, because it really is obvious. But I see very little code where all my "whys" are clearly answered by the "whats" of the code.

As has already been remarked: Documentation and comments are different things. Yet, lots of programmers put markup on their code comments and use tool to extract them to a separate PDF or HTML, and claim that as their "documentation" of their software. If you accept their claim, then the borderline between comments and documentation is rather fuzzy. If you rejec JavaDoc and Doxygen and Pydoc and the whole crop of these "documentation generators", you are offending a lot of today's programmers.
GeneralRe: The Premise is wrong Pin
Sander Rossel14-Aug-19 1:49
professionalSander Rossel14-Aug-19 1:49 
GeneralRe: The Premise is wrong Pin
kalberts13-Aug-19 20:55
kalberts13-Aug-19 20:55 
GeneralCode Samples? Pin
PeejayAdams11-Aug-19 22:32
PeejayAdams11-Aug-19 22:32 
GeneralRe: Code Samples? Pin
Slacker00712-Aug-19 1:12
professionalSlacker00712-Aug-19 1:12 
GeneralRe: Code Samples? Pin
PeejayAdams12-Aug-19 1:22
PeejayAdams12-Aug-19 1:22 
GeneralRe: Code Samples? Pin
Chris Maunder12-Aug-19 3:06
cofounderChris Maunder12-Aug-19 3:06 
GeneralRe: Code Samples? Pin
kalberts13-Aug-19 1:08
kalberts13-Aug-19 1:08 
AnswerOther : it shows how it looks like / it shows/explains how it works Pin
Ralf Meier11-Aug-19 22:05
mveRalf Meier11-Aug-19 22:05 
GeneralRe: Other : it shows how it looks like / it shows/explains how it works Pin
ronlease12-Aug-19 2:41
professionalronlease12-Aug-19 2:41 
GeneralBug - Spelling mistake Pin
Amit Joshi CP11-Aug-19 21:14
Amit Joshi CP11-Aug-19 21:14 
GeneralOther [along with standard options] Pin
Amit Joshi CP11-Aug-19 21:18
Amit Joshi CP11-Aug-19 21:18 

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.