|
If it's documentation for software developers then yes - must include code samples.
By "users" I mean "business users" - the non-technical staff that use the software we produce.
So the "application" that I've inherited to support has "technical docs" intended to show a programmer how it works, standing data that needs to be maintained, known issues etc. A subset of that is intended for the Change Management Team and describes how to promote upgrades into production.
The "business documentation" is intended to show an office worker (aka "user") how to use the application - "Enter your client code here and press this button" type of thing.
Clear as mud now 
|
|
|
|
|
It's 2019. I m looking for video/gif/screen shots in example.
Life is a computer program and everyone is the programmer of his own life.
|
|
|
|
|
I will run a mile from any documentation that includes a gif. Same goes for video.
Give me screenshots, images and text any day.
I'm just a Luddite at heart
|
|
|
|
|
Crikey, no. I despise the trend toward everything being video these days. Give me text that I can peruse at my speed, and, most importantly, back up in and cross reference thoughts. Extremely difficult to do that with video.
Not that video doesn't have its place. It should be a supplement, not the main part.
|
|
|
|
|
Gads, I despise video. Not searchable, time wasting listening to some person talking slowly, and most of the time in an accent I can't understand.
|
|
|
|
|
Every now and then you see really high quality instructional videos, often made by commercial intrests: I've got a small handful of videos showing you, step by step, how to cast a concrete floor, how to put up wall paper, how to install your new central vacuum cleaner. The instructors are not rushed, but there is no wasted time. Images are sharp and clear, closeup when needed, overview when more suitable. Divided into chapters corresponding to the work steps.
Such videos exist, but they are few and far between. Those craftsman videos were published on DVD; if you take that expense, you want to do a decent job.
The vast majority of "instructional" videos on YouTube bear no sign of professionality, neither in the instructional contents nor in the video quality; they often look as if they are made by the teenager next door who are testing out the video functionality of his new smarphone. Some are made by a manufacturer, using "instructions" as a poor disguise for advertising: The essential thing is to show how great his product is, and how you can extend it with plugins bought at a very favorable price.
And then there are those - both as videos, plain web pages and printed books - that says "Don't worry, just do these steps one by one to solve your task - you don't have to understand a thing, if you just know what to do". These are the ones that really offend me the most. I feel that I am not being taken seriously as a learner, as a user. I have had too many own experiences where it took me a long time to get beyond the very most elementary level because noone was able to make me understand the inner workings.
And, nowadays I more or less have to hold back my colleagues, forcing them to listen to an explanation of how things work - they insist on me just telling them what to do. No, I say - then you will be back in a few days with another problem you are unable to solve because you did't understand how it works. Listen to me, and you can handle the next problem yourself! ... This is far more expressed with young people; they are far less willing to "waste" the time om obtaining any deeper understanding. So they are far more satisfied with those cursory explanations that solves the immediate problem, and that is it. Deeper understanding is for oldtimers, it seems.
|
|
|
|
|
I think any documentation without an overview of what the product is capable of doing is not a good documentation.
|
|
|
|
|
The best documentation in the world is useless unless I can find within seconds the answer to what I'm looking for. The things I quite often see:
* Search sucks, if it exists at all.
* If I Google search, I end up find stale links to screenshots or step-by-step instructions that no longer work because the product has changed. SalesForce is the worst in this category in my experience.
* I should be able to find in your documentation the answer, not on Stack Overflow. Yeah, dream on, Marc.
* FFS, it's the age of automation. How about making your documentation "living" -- let me log in and add my own comments for future reference. Don't bother with whether they are public or private, I get you don't want to be a moderator, just make them private to me.
etc.
|
|
|
|
|
Marc Clifton wrote: * I should be able to find in your documentation the answer, not on Stack Overflow.
I was considering using a free, open source system with a really glossy web presentation. But they were rude enough to make "support" an entry in their description, that said "Support: Community".
Sorry, you lost twenty points there. When you really mean: "Support: None whatsoever", but try to present it as something positive using the "community" buzzword, then I ask myself: In which other ways are the trying to fool me?
|
|
|
|
|
Documentation doesn't convince the user to use the application. It helps them understand the application.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
#realJSOP wrote: It helps them understand the application.
Exactly
|
|
|
|
|
It depends. A long, long time ago, when software shipped in boxes with printed manuals, the manual for MS Flight Sim 5 was so great that seeing it at my local computers shop convinced me to buy and use the application. Or rather, it convinced me to convince my mom to buy it for me so I could use it. 
If we're talking about a framework or library I'm thinking of using as part of an app I'm working on, then the presence of good documentation can definitely convince me to choose one tool over another.
|
|
|
|
|
I disagree.
Documentation is actually a form of marketing and is used as such. When reviewing a component or service developers will often check the docs (if a company is smart enough to have them online) in order to see if the API is sensible, if the docs are complete enough to actually allow the product to be used, and to show what sort of effort has been put into supporting a dev post sales.
cheers
Chris Maunder
|
|
|
|
|
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.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
