Writing a User Manual
-
TPFKAPB wrote:
Real men don't read manuals.
..ever since the introduction of the word "discoverability", and the omission of a user-manual with Windows, I've been working under the idea that software-interfaces should be predictable, self-explanatory and intuitive. A manual that says "click here to do X" does not really help much. A reference OTOH.. FWIW, you're implying that a programmer cannot be a real man :)
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
How long before the next airliner comes without manuals? Just two big buttons in the cockpit labelled "up" and "down". Then again, it seems even real aircraft engineers don't read manuals:
"Enter the Arab flight crew of Abu Dhabi Aircraft Technologies (ADAT) to conduct pre-delivery tests on the ground, such as engine run-ups prior to delivery to Etihad Airways in Abu Dhabi ... The ADAT crew taxied the A340-600 to the run-up area. Then they took all four engines to takeoff power with a virtually empty aircraft. Not having read the run-up manuals, they had no clue just how light an empty A340-600 really is. The takeoff warning horn was blaring away in the cockpit because they had all 4 engines at full power. The aircraft computers thought they were trying to take off, but it had not been configured properly (flaps/slats, etc..) Then one of the ADAT crew decided to pull the circuit breaker on the Ground Proximity Sensor to silence the alarm. This fools the aircraft into thinking it is in the air. The computers automatically released all the brakes and set the aircraft rocketing forward. The ADAT crew had no idea that this is a safety feature so that pilots can't land with the brakes on. Not one member of the seven-man Arab crew was smart enough to throttle back the engines from their max power setting, so the $200 million brand-new aircraft crashed into a blast barrier, totaling it."
The above is the "urban myth" version of the story. What is supposed to actually have happened is that no-one thought to chock the wheels prior to a full engine run-up. The brakes aren't powerful enough to hold against full engine thrust so the plane moved forward. "Surprise led the ground-test technician to focus on the braking system, so he did not think about reducing the engines' thrust," and the problem was supposedly compounded by the attempts to steer away from the wall, which decreased hydraulic pressure on the braking system, effectively releasing the brakes. [I for one find it hard to comprehend that in a $200M airbus, the nosewheel steering system and the braking system share a single hydraulic circuit...???] Whichever version of the story you choose to believe, a little more attention to the manual before the tests started might have been beneficial...
-
How long before the next airliner comes without manuals? Just two big buttons in the cockpit labelled "up" and "down". Then again, it seems even real aircraft engineers don't read manuals:
"Enter the Arab flight crew of Abu Dhabi Aircraft Technologies (ADAT) to conduct pre-delivery tests on the ground, such as engine run-ups prior to delivery to Etihad Airways in Abu Dhabi ... The ADAT crew taxied the A340-600 to the run-up area. Then they took all four engines to takeoff power with a virtually empty aircraft. Not having read the run-up manuals, they had no clue just how light an empty A340-600 really is. The takeoff warning horn was blaring away in the cockpit because they had all 4 engines at full power. The aircraft computers thought they were trying to take off, but it had not been configured properly (flaps/slats, etc..) Then one of the ADAT crew decided to pull the circuit breaker on the Ground Proximity Sensor to silence the alarm. This fools the aircraft into thinking it is in the air. The computers automatically released all the brakes and set the aircraft rocketing forward. The ADAT crew had no idea that this is a safety feature so that pilots can't land with the brakes on. Not one member of the seven-man Arab crew was smart enough to throttle back the engines from their max power setting, so the $200 million brand-new aircraft crashed into a blast barrier, totaling it."
The above is the "urban myth" version of the story. What is supposed to actually have happened is that no-one thought to chock the wheels prior to a full engine run-up. The brakes aren't powerful enough to hold against full engine thrust so the plane moved forward. "Surprise led the ground-test technician to focus on the braking system, so he did not think about reducing the engines' thrust," and the problem was supposedly compounded by the attempts to steer away from the wall, which decreased hydraulic pressure on the braking system, effectively releasing the brakes. [I for one find it hard to comprehend that in a $200M airbus, the nosewheel steering system and the braking system share a single hydraulic circuit...???] Whichever version of the story you choose to believe, a little more attention to the manual before the tests started might have been beneficial...
-
I understand your point; however, I think it's a bad example. I'd like to think the guy flying a plane I'm in has done quite a bit more than read the manual.
-
I agree absolutely, unfortunately a skill many of us fail to learn.
Unfortunate indeed.
Anna :rose: Tech Blog | Visual Lint "Why would anyone prefer to wield a weapon that takes both hands at once, when they could use a lighter (and obviously superior) weapon that allows you to wield multiple ones at a time, and thus supports multi-paradigm carnage?"
-
You're lucky your application requires only several days of work for an user manual.
To alcohol! The cause of, and solution to, all of life's problems - Homer Simpson ---- Our heads are round so our thoughts can change direction - Francis Picabia
-
I thought it was "Real programmers don't need error messages." Once when I purchased a cellphone the salesman offered to show me how to set my name. I declined saying I'd just RTFM. He smiled, and smiled some more, and finally said, "You just made my day."
Psychosis at 10 Film at 11 Those who do not remember the past, are doomed to repeat it. Those who do not remember the past, cannot build upon it.
-
Nowadays, things are expected to just work, so manuals may be ignored, until something breaks in a terrible, awful way. :)
CEO at: - Rafaga Systems - Para Facturas - Modern Components for the moment...
-
Try incorporating some nonsense statements and see if anybody notices... :-D "Click the Fubar button in the lower right corner. Then paint the horse yellow and fly away to the moon! If that doesn't work, please contact the [Insert company name here] helpdesk."
Why can't I be applicable like John? - Me, April 2011
-----
Beidh ceol, caint agus craic againn - Seán Bán Breathnach
-----
Da mihi sis crustum Etruscum cum omnibus in eo!
-----
Just because a thing is new don’t mean that it’s better - Will Rogers, September 4, 1932Quite a few years ago, I did the same thing but slightly differently. We were producing a paper report (I said a "few years ago" - probably should have said a "few decades ago"). The report was about six inches thick of "standard computer paper". About 30 copies were produced once a month. I mentioned to my boss that I suspected that no one ever even looked at the report and suggested that we randomly place 10 pages that just contained the one line "If you need this report, contact extension 1234". He agreed and we ran the report for six months without ever hearing from anyone. We discontinued the report. About a year later, someone called to ask if his copy was being mis-delivered. But we didn't restart the report.
Gus Gustafson
-
Uggghh!! I hate documentation, but it has to be done...and then maintained. A real pita when only a handful of users will ever want it...like the old standard of having a Help button on every screen that nobody every clicks. Still, reviewing the User Manual and using self-help options are part of new user training...whether or not they actually ever use those resources is anybody's guess.
"Go forth into the source" - Neal Morse
-
It depends on the type of manual, how it will be delivered/maintained and the audience it will have. The pages for the manual I wrote for Visual Lint[^] are among the busiest on our website, so the many hours I put into working on it (valuable coding time!) have definitely been worthwhile. I am of the opinion that being able to write good technical content is an essential skill for a software developer, so even if the content is not going to be particularly useful to anyone you can look at it as a useful training exercise.
Anna :rose: Tech Blog | Visual Lint "Why would anyone prefer to wield a weapon that takes both hands at once, when they could use a lighter (and obviously superior) weapon that allows you to wield multiple ones at a time, and thus supports multi-paradigm carnage?"
My experience has been, if writing the user manual for an application is at all difficult, maybe the UI for the application isn't designed well. I've learned this lesson all too well with applications I've designed :sigh:.
Software Zen:
delete this; -
Excellent idea. I've done similar things - for example, when a user imports a file I log the original file name and the location from which it was imported. I'm definitely going to be logging the save locations from now on as well. +5 to you.
Windows applications have a MRU (most recently used) list telling you on the files menu where the last 10 files were saved and their names.
-
Why, then, is it called _man_ual? ;)
Because it is not automatically intuitive how to use the software?
-
I agree absolutely, unfortunately a skill many of us fail to learn.
That's why we all went into programming. A lot better use of the language.
-
How long before the next airliner comes without manuals? Just two big buttons in the cockpit labelled "up" and "down". Then again, it seems even real aircraft engineers don't read manuals:
"Enter the Arab flight crew of Abu Dhabi Aircraft Technologies (ADAT) to conduct pre-delivery tests on the ground, such as engine run-ups prior to delivery to Etihad Airways in Abu Dhabi ... The ADAT crew taxied the A340-600 to the run-up area. Then they took all four engines to takeoff power with a virtually empty aircraft. Not having read the run-up manuals, they had no clue just how light an empty A340-600 really is. The takeoff warning horn was blaring away in the cockpit because they had all 4 engines at full power. The aircraft computers thought they were trying to take off, but it had not been configured properly (flaps/slats, etc..) Then one of the ADAT crew decided to pull the circuit breaker on the Ground Proximity Sensor to silence the alarm. This fools the aircraft into thinking it is in the air. The computers automatically released all the brakes and set the aircraft rocketing forward. The ADAT crew had no idea that this is a safety feature so that pilots can't land with the brakes on. Not one member of the seven-man Arab crew was smart enough to throttle back the engines from their max power setting, so the $200 million brand-new aircraft crashed into a blast barrier, totaling it."
The above is the "urban myth" version of the story. What is supposed to actually have happened is that no-one thought to chock the wheels prior to a full engine run-up. The brakes aren't powerful enough to hold against full engine thrust so the plane moved forward. "Surprise led the ground-test technician to focus on the braking system, so he did not think about reducing the engines' thrust," and the problem was supposedly compounded by the attempts to steer away from the wall, which decreased hydraulic pressure on the braking system, effectively releasing the brakes. [I for one find it hard to comprehend that in a $200M airbus, the nosewheel steering system and the braking system share a single hydraulic circuit...???] Whichever version of the story you choose to believe, a little more attention to the manual before the tests started might have been beneficial...
Don't confuse following checks lists with RTFM, sir! And about:
Quote:
[I for one find it hard to comprehend that in a $200M airbus, the nosewheel steering system and the braking system share a single hydraulic circuit...???]
Most modern airliners have at least two hydraulic circuits backing up each other. The A340 has three. If your're interested: http://pmgasser.ch/airbus_memos/downloads/A340_HYD.pdf[^] Regs, Christian