|
If we push the responsibility onto the documentation writer, we can - as software developers - make sure that none of us will be blamed. We never do any sort of documentation writing!
|
|
|
|
|
Yeah, I do all of my own documentation. I know the code best, so it makes sense.
|
|
|
|
|
Like, I am a car mechanic, knowing the car best, so I am the one who should teach you how to drive in heavy city traffic.
If you are talking about software maintenance documentation, you may be the best person to write that documentation - although I have seen some outright awful attempts by software guys to write even that sort.
For the end user documentation, you need a domain expert. If the domain is software development - say, you are making development tools for the FOSS community - then you may be domain expert, knowing in detail the problem(s) to be solved, well established work patterns and solutions, the professional terminology (domain specific), etc. etc. If you are a good writer, maybe you are the one. ("Good writer" covers both mastering the language, and the skill to organize the information in proper ways.) If you are writing software to be used in areas where you are not a domain expert, then leave user documentation to someone else.
|
|
|
|
|
It isn't always obvious that documentation is incorrect: it's written by people who should know what to do for people who don't.
What's "obviously incorrect" may be clear when your GPS tries to send you via a river rather than a road, but in software it's never that cut and dried.
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
|
Totally agree.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment
"Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst
"I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
|
|
|
|
|
Since the hypothetical situation states that the documentation was obviously (in this context obvious to the user) incorrect, then the user was invoking the documentation as authority rather than taking responsibility for their action. There is plenty of fault upstream of the user but it doesn't relinquish the user of using good judgement.
|
|
|
|
|
I love this example because it allows to portray how even then the user cannot possibly be held accountable because there is no certainty the obvious will be noticed, because:
- Even when it is obviously heading towards a river, the user may realize it too late (you still need to maintain focus on the driving rather than the GPS or the possibility it may be blatantly wrong).
- The user may be colorblind, you cannot assume that anything will be obvious to any user. The river may look the same as the road for certain users.
- The user may take for granted that the manual should be trusted and his suspicions are incorrect. It is the responsibility of the supplier to review and correct it. If it is so obvious to the user it would be even more to the supplier and failing to properly review it is at the suppliers fault.
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
|
|
|
|
|
There's no such thing as "obvious" that covers every user. If the software/hardware/documentation allows something to happen, some user somewhere will make it happen.
|
|
|
|
|
In my view, partially correct. It's not the user (definitely) but it's not the docs either. The docs are never read so how can they be at fault?
cheers
Chris Maunder
|
|
|
|
|
The issue is in the whole process that lead to the event, not the failure of a single actor, the documentation writer made a mistake that went unchecked (possibly because the project wasn't properly explained to them), the software wasn't properly tested and the hardware wasn't resilient enough.
The only possibility in which the user could have been considered at fault would be if they didn't read the (incorrect) documentation 
Edit: it's nice to see that nobody blamed exclusively the sw dev
|
|
|
|
|
It's important to identify the source or sources of the problem in order take measures to reduce the likelihood of it happening again.
|
|
|
|
|
Absolutely, but identifying the source of problems has nothing to do with finding a singular scapegoat that is "at fault" which will reduce the probability that someone will flag their mistake early and instead hope nothing will happen.
And consider that scapegoating is especially harmful when we know many problems exist and are not caused by a single person
|
|
|
|
|
Sometimes it is necessary, specially on customer and provider relationship.
It needs to be done so for damage compensation purposes. In such a situation who's to blame is important on the broad scope, less important on the customer's and provider's own scopes. Then it is important to identify the flaws in the process that could've prevented the issue on either side.
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
|
|
|
|
|
Either multiple choice or better choices.
The only one that is NOT guilty (in my opinion) is the user. All the rest should be, at least partly, liable.
M.D.V. 
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
Yep.
"the debugger doesn't tell me anything because this code compiles just fine" - random QA comment
"Facebook is where you tell lies to your friends. Twitter is where you tell the truth to strangers." - chriselst
"I don't drink any more... then again, I don't drink any less." - Mike Mullikins uncle
|
|
|
|
|
Since the hypothetical situation states that the documentation was obviously (in this context obvious to the user) incorrect, then the user was invoking the documentation as authority rather than taking responsibility for their action. There is plenty of fault upstream of the user but it doesn't relinquish the user of using good judgement.
|
|
|
|
|
Doug Domeny wrote: in this context obvious to the user
I didn't see it like this.
If the user knew it was wrong... then he has part of responsibility too.
M.D.V.
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
where the project manager in this list
company accepting fault and helping to resolve the issue, if in money or replacement
release statement that fault, and follow up other sales
programmer can add some fault tolerance next time
documentation and tester crossover that documentation followed for issues
work environment that allows for implementation errors to be raised, tracked, and resolved and retested.
|
|
|
|
|
Incorrect documentation and designing a system that is not intuitive to use and requires following a manual to use it correctly.
Some companies do not care to keep internal and customer documentation up to date.
I follow the fool-proof principle (aka defensive design) that the system should be designed in a way that is difficult to use incorrectly and easy/intuitive to use.
|
|
|
|
|
Shao Voon Wong wrote: I follow the fool-proof principle (aka defensive design) that the system should be designed in a way that is difficult to use incorrectly and easy/intuitive to use.
Fail safe systems fail by failing to fail fail safe.
|
|
|
|
|
The Boeing 737 Max MCAS bug, for which the end-users (pilots) took the initial blame.
|
|
|
|
|
Well.... expensive and deadly enough....
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
