Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

So, in the documentation, "all" was very unclear. Users guessed that "all" meant all in the company while it mean all in the whole world!

So, wildly ambiguous, unclear, dangerous product documentation.

Could clear that up by being really clear and explicit about "all in the world", "all in the company", "all in a particular project", etc. and then lots of very clear examples.

But it was easier just to have some check box, icon, etc. described as "all".

In current computing, such documentation nonsense is usually resolved by the usual way of making sense of a computer user interface, experimentation, or use the TIFO method (try it and find out), or throw the options and combinations of options over and over against a wall to see which ones appear to stick, or do the usual, my usual description, "mud wrestling", all due to bad documentation.

It is as if the software were designed and written by people who thought that a check box with "all" was all there was to the work.

Well, in this case the TIFO experimentation involved hundreds of Fortune 500 companies and many other organizations, small to the largest, around the world.

It is as if the documentation writers were inarticulate and essentially illiterate.

So, Xerox PARC thought that some buttons, say, as on a microwave oven, would be sufficient for controlling lots of Xerox office machines. Then the computer industry, with graphical user interfaces thought that nearly all of computing could also have such a user interface. Nope: Commonly even makers of microwave ovens have well written users guides. The many millions of Web site user interfaces are generally much more complicated to control than a microwave oven and also need good DOCUMENTATION, e.g., much more then cryptic, not a chapter, paragraph, or sentence, not with examples, clear definitions, etc., but just a word or two from a roll over. And often there is just an icon, can't pronounce it, can't spell it, can't type it in text, can't send it in e-mail, can't look it up in a dictionary or with a search engine -- which takes us back to pictographs before the Roman alphabet. That situation, in technical language, is a bummer; more clearly a disaster as the OP shows.

IMHO, a good candidate for the biggest bottleneck in the future of computing is the quite general lack of good technical documentation.

E.g., two weeks ago I signed up with a different Internet access provider (ISP). They promised me I could have up to five e-mail addresses. Sooo, I tried to get a second address for the alpha test I plan for my project (Web site -- no icons!). It took 14 hours of my time and nearly that much time with third level technical support. With decent documentation, I could have done all the work in about 10 minutes. But, three days ago their Internet service quit in my neighborhood. Their efforts to reset my equipment (cable modem, IP router, WiFi connection) make my connection from before the outage work no longer. The fix took a day and a half, about 30 hours of my time, and about 15 hours on their third and fourth level technical support. With decent technical documentation, I could have fixed the problem myself in 10 minutes. And I have MANY other such examples. Several hours or days instead of a few minutes -- HUGE bottleneck to progress.

I say again: One of the worst bottlenecks in the future of computing is the lack of decent technical documentation, in a natural language, e.g., English, and mostly in text. No joke, guys. Icons, check boxes, radio buttons, text boxes, pull downs, pop ups, roll overs, etc., are NOT and can never be good natural language technical documentation.

TIFO on world-class issues is a huge disaster waiting to happen.



I'm all for good documentation, because not everyone learns in the same way, and if you have a product as broadly used as Jira, I think its user base deserves it. But in the basis it's just an inefficient, after the fact attempt to mitigate poor UI/UX. Which could EASILY have been clearer about the access rules, and they could (should) have defaulted to a more restrictive setting. First of all to protect users against the clearly more damaging of the two extremes (too restrictive versus not restrictive enough) but also because it better fits Jira's nominal use case.


Yup: Their "all" was a high powered, loaded gun, cocked, no safety, hair trigger, ready to go off at any time.


I take your point about icons without text but I would guess for 90% of people all the buttons on the microwave are blank except the time keypad, the start button, and maybe the power level setting. No one reads the manual.


I just moved and now have a refrigerator that promises to make ice and dispense it.

Well, it didn't make ice. Since it would dispense water, the water line WAS connected and working.

Well, the front door has lots of buttons. They didn't help.

Finally the solution: Look in the freezer. At the top pull out a complicated plastic piece of unknown utility. For me, bend down, look up, look at the back wall of the freezer in the upper left corner, and see a switch, ON-OFF. It was OFF. Now it's on, and the ice maker is working!

I needed a manual and didn't have one.

The documentation I mentioned is important, for microwave ovens, fancy refrigerators, and certainly for the user interface of high end software that can have disasters such as in the OP.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: