|
There's no such thing as decent documentation (that I've seen) for dev components.
Beyond that, the survey STILL isn't clear. It implies we're talking about an application, and then goes into dev framework questions, which is NOT the same thing.
So what is it that we're talking about?
|
|
|
|
|
- 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.
- 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
- It provides information targeted towards novice users
- It provides information targeted towards advanced users
This is applicable to pretty much anything related to documentation in IT.
- 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.
- It lists common API calls
- Is comprehensive and covers every possible scenario (within reason)
- 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
|
|
|
|
|
Chris Maunder wrote: So tell us what would make deceny documentation.
The absence of typos, for one. 
/ravi
|
|
|
|
|
You get that with the pro subscription.
cheers
Chris Maunder
|
|
|
|
|
/ravi
|
|
|
|
|
|
A lack of documentation can convince me not to buy it.
|
|
|
|
|
Sander Rossel wrote: A lack of documentation can convince me not to buy it.
True story[^] (see pet peeve #1)
/ravi
|
|
|
|
|
To me, comments and documentation are different things.
I don't write comments, maybe one or two a year.
See also Write comments that matter[^]
I have been trained to ignore comments because they were never any good.
Writing (and maintaining) good comments is probably harder than writing good code 
Totally agree on #2 though.
Some developers have the idea that the software is for them and the users are only granted permission to use it 
|
|
|
|
|
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.
|
|
|
|
|
Member 7989122 wrote: Lots of the examples in your link of poor commenting are not "poor", but outright silly
Then why have I seen them so often?
I don't like comments because you're supposed to write comments.
That's kind of a thing, you either write comments or you're a bad programmer who doesn't take pride in his work.
The result is that a lot of programmers write comments for the sake of commenting.
And then you get comments like product.Save(); // save the product
Which gets copy/pasted.
Or the code gets changed, but the comments don't.
Every comment is a line of code that has to be understood and maintained.
And sometimes the comment is more cryptic than the code!
That's because the code that needs to be commented, often can't be explained on one or two lines.
For public API's I'm a fan of using the /// kind of comments (what are they called?).
At least you'll see what a function and parameters do.
A parameter like "fileName" could have the explanation "Complete file name including path." and at least you'll know what's expected.
It could be solved by naming it fileNameInclPath, but that gets tricky quite fast.
|
|
|
|
|
I worked on a project in need of a record management library. It would have to be open source, as we were going to extend it significantly. We found one that - according to the description - fufilled all our needs, so we got hold of it. Fortunately, it didn't cost us any money. The code was well commented, each function wiht a (presumably) descriptive heading, comments before loops and other control structs, and lots of end-of-line comments. But I can't comment on the quality of the code: It was all in French. All variable names were in French, too. None of the project members could read French.
So we had to go on searching for another library. Maybe we threw out the best alternative because of its comments. Maybe variable names in English and no comments at all would have made us go for it. And I didn't feel comfortable with the alternative that we settled on.
|
|
|
|
|
Not sure why you'd ever put them in documentation but there ought to be a law that says they should appear in sales brochures.
Whenever you find yourself on the side of the majority, it is time to pause and reflect. - Mark Twain
|
|
|
|
|
??
Ever try to use log4net or NLog without code examples in their documentation? That is just one example out of thousands for why "most" documentation needs code examples and example usage; especially if you are not used to working with the product, etc.
|
|
|
|
|
Yes, I see what you mean for API calls etc., examples are a must. I was thinking more of documentation for products where you don't get to interact with the code-base.
Whenever you find yourself on the side of the majority, it is time to pause and reflect. - Mark Twain
|
|
|
|
|
Never in a million years would I use a product whose doc didn't contain code samples.
cheers
Chris Maunder
|
|
|
|
|
That depends... You seem to be assuming that "documentation" means "documentation targeted at programmers". I can very well imagine documentation for an accounting system, a video editor or a computer game that does not contain code samples.
You may of course argue that "Clicking this button is the equivalent of calling an API, so for documentation purposes, illustrating the effect of clicking the button is a code sample". OK, I'll accept that, but to me that is twisting it quite a bit.
|
|
|
|
|
It depends on what is documented.
If it is an UI-Element it is useful when the documentation shows how it looks like.
Generally it is useful if the documentation shows and/or explains how it works ...
|
|
|
|
|
Exactly! Documentation should focus on the why much more than the how. What assumptions were made? What are the general inputs and outputs? What's the life expectancy of the application? What critical technologies are involved? Stuff like that. If organizations need documentation to explain the code itself (at least at a low level), then code is quite likely badly written.
|
|
|
|
|
I think
Is is comprehensive and covers every possible scenario (within reason)
should be
It is comprehensive and covers every possible scenario (within reason)
Amit Joshi
Value of the value is valued only if its value is valued.
|
|
|
|
|
It separates the Beginner and Advanced sections. That way, it is easy for both types of the users to look into.
Amit Joshi
Value of the value is valued only if its value is valued.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
