|
CHill60 has a good start below; let's expand on it a bit. He says you have to "consider your audience". Based on Chris M's comments elsewhere in the forum, that audience is us: developers. The product being documented is a software package or application that the software we develop is going to interact with in some way.
I put to you that the purpose of all product documentation is the same: answer the questions that the product itself does not answer by its very nature. We now need to figure out two things: what are the questions developers are likely to ask, and how should we frame the answers?
When you 'consider the audience', you should realize first and foremost that the developer is using your product to solve a problem or meet a requirement in his own task. Your product is not an end in and of itself. What are the problems he's trying to solve? What are the forms his solutions are likely to take? Remember that, while you may have the hottest hyper-fulcrum-folding-widget in town, all he cares is that he puts fulcrums in one end, and they come out neatly folded at the other. Just because he's another developer should you think he's going to be impressed by the fact that your fulcrum folding algorithm is based upon a neural network of free-form monads linked in a five-dimensional matrix of polytonic properties. He just wants his fulcrums folded, no muss, no fuss.
Knowing the questions will often suggest at least the form the answers take:- "What's a fulcrum, and why do I need to fold it? My boss says I've got to have this done by the weekend." - Here's an introduction on fulcrums, plus a tutorial for doing basic folding using our product.
- "What's the API?" - reference documentation plus complete working samples that use most, if not all, of the API.
- "How do I create fulcrums that your widget can handle?" - Define your fulcrum format, give them a library that produces validated fulcrums (fulcra?) from basic input. Maybe fulcrums have an ANSI standard representation, parts of which are optional. Tell them which options you support, which ones you don't, and why.
- "I need to multithread my fulcrum folding with my retrograde spinnaker production. How do I do that?" - If that's a common thing, give them a sample that at least shows the highlights.
All of these statements have the same intent. In order to have good product documentation, you must have the ability to place yourself in that documentation consumer's shoes and address his needs. We as developers love simple solutions to this problem, which explains why doxygen and similar products get so much traction. Unfortunately those products only work when used to create reference documents. All too often we developers have to make do with this kind of documentation, along with the source for one or two brief sample programs.
TL;DR: It depends. 
Software Zen: delete this;
|
|
|
|
|
|
There should be an "All of the Above" option
|
|
|
|
|
Programmer's documentation and end user documentation alike: Lots of it provides a whole bunch of details without guidance to how it fits together, and from the pieces of information that the reader can intially grasp, he builds his own mental infrastructure ... which may be quite wrong and misleading. It takes a long time to un-learn as he reads to the end of the documentation, and usually even a lot of practical experience to realize that the initial concepts were incorrect.
I was in a few software projects where the first thing we did was developing an Entity-Relationship data model with the customer, showing how all of the information related to each other. Only after having discussed that overall model with the customer did we start code design. This was truly great for communicating to the users, the customer, how the software actually operated on the data.
Similarly when I need to learn some new code base: I look for descriptions of major data structures and how they fit together, how processes and modules interact, at the overall level. Later, I can dive down to the specific APIs, but first I must know its place in the world. That is what documentation is for! The specific APIs can be found in the code. There is no real reason to extract API declarations and comments lines and make a PDF file out of it: When I need it, I can find it in the code. I need documentation for what I can not easily see from the code.
|
|
|
|
|
You took the thoughts right out of my head.
How did you get in there and when will you leave?
You have no idea how dangerous a neighborhood you're in between my ears. 
Cheers,
Mike Fidler
"I intend to live forever - so far, so good." Steven Wright
"I almost had a psychic girlfriend but she left me before we met." Also Steven Wright
"I'm addicted to placebos. I could quit, but it wouldn't matter." Steven Wright yet again.
|
|
|
|
|
The biggest problem with documentation is that noone has taken the time to explain things in an instructive, pedagogical way. Lots of "documentation" today is little but a summary of the function declarations, automatically extracted and formattet. That doesn't qualify as documentation - just as a source code extract. That is something different.
|
|
|
|
|
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 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
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
