|
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
