|
Right. So more of the why you'd use a particular API and where you would use it (what situation) rather than the "how".
cheers
Chris Maunder
|
|
|
|
|
Documentation for users should not include code samples just as technical documentation should not include information targeted towards novice users. If it's a Documentation package then all of the above for me
|
|
|
|
|
I'm totally confused so maybe you need to clarify what you mean by "documentation" and also what you mean by "users". I honestly didn't think there'd be any interpretation here other than "the instructions, comments, and information for using a particular piece or system of computer software or hardware" (paraphrased from Webster), and "software developer making use of said software or hardware".
Why would the docs not include code samples? It's for software developers?
cheers
Chris Maunder
|
|
|
|
|
It depends on the product and the product determines the users. If the product is a software library then it makes sense to have code samples. If the product is an application then code samples are usually not appropriate.
In my opinion.
"They have a consciousness, they have a life, they have a soul! Damn you! Let the rabbits wear glasses! Save our brothers! Can I get an amen?"
|
|
|
|
|
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 doesn't imply we're talking about an application at all. Let's go through each option one by one.
- 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
|
|
|
|