Ask Slashdot: Should You Invest In Documentation, Or UX? 199
New submitter fpodoo writes "We are going to launch a new version of Odoo, the open source business apps suite. Once a year we release a new version and all the documentation has to be rewritten, as the software evolves a lot. It's a huge effort (~1000 pages, 250 apps) and it feels like we are building on quicksand. I am wondering if it would be better to invest all our efforts in R&D on improving the user experience and building tools in the product to better help the user. Do you know any complex software that succeeded in avoiding documentation by having significantly improved usability? As a customer, how would you feel with a very simple product (much simpler than the competition but still a bit complex) that has no documentation?"
UX (Score:4, Interesting)
Poor documention = Poor perception (Score:4, Interesting)
If you want your software to be taken seriously by anyone outside of a tiny niche, bite the bullet and get a decent technical writer to write decent documentation. Sloppy documentation is equated (usually rightly) with sloppy coding, sloppy security, and an overall sloppy effort.
Depends on the target: (Score:4, Interesting)
If the idea is that the product will be set up and administered by the customer's IT minions(internal, contract, or purchased 'as a service'), then Please, Please, Please document. IT minions are largely innured to the suffering of merely bad, hostile, and unintuitive software; but they are the most likely to need to know how things fit together, where they may need to bodge some shim together and keep an extra close eye on things, and so on. They won't like it; but they'll like it a whole lot more than an equivalent product where they need to deploy a mixture of reverse-engineering and pure mysticism because the system is a total black box.
Re: You're doing it wrong. (Score:5, Interesting)
At the end of the day, your users have a business goal, and you've sold them on the idea that your software package will help them achieve it better and more easily than other solutions. You sell solutions and solution components, but you also sell 'better' and 'more-easily'. Documentation is necessary, no amount of UI will take you from splash screen to solution whilst navigating a large set of outcomes and a series of interdependent choices.
DO provide UI reference, but scenario-driven documentation is your users' greatest need.
DO automate common, simple tasks to the extent possible.
DO make doing the right thing easy, and wrong or dangerous things hard.
DO bring the most relevant information into the app in abbreviated form (apply the 90/10 rule)
DO link the UI to relevant documentation.
DON'T get hung up on covering every possible scenario (again, 90/10 rule)
DON'T believe that a perfect UI avoids the need for documentation.
DON'T try to bring all the documentation into the UI.
DON'T rely on your own intuition about what's common or difficult for users, ask them or collect the data.
Mod parent up! (Score:5, Interesting)
Do this.
And make the error reports unique. No more "an unexpected error has occurred". Even "purple-monkey-dishwasher" is better than that. Make it easy for your users to report real problems to your developers. And that means making each error unique enough that the developers can search the code for it.
And have someone spend some time sorting through your forums (make sure you have forums) who can move threads and messages around while still maintaining the links to them. So someone with a "purple-monkey-dishwasher" error can see the other posts about that WITHOUT having to dig through unrelated "vitamin-can-hook" errors. Sortable by version. And by date.
Re:When every feature undocumented (Score:4, Interesting)
That's interesting because I see people on a daily basis fumbling with the debit/credit machines at checkouts. Even with basic things like swiping their cards. A big pain point is also becaue each one for each store chain has to be different in unnecessary and inconvenient ways.
Any software requiring documentation is broken. (Score:5, Interesting)
Any software requiring documentation is broken.
I blame Bob Wallace.
Bob Wallace was one of the originators of the concept of "shareware", and he got paid not for his software. This made people wonder how Quicksoft was able to stay in business.
When questioned about this at one convention, he made circling motions with his hands on either side of his head, and said "Software is ... all up here ... it's not real, it's ephemeral. I don't sell software, I sell manuals". So Quicksoft made its money, and its livelihood in the margin between the cost of mass-producing a manual vs. printing it out from a floppy disk and using up a bunch of tractor feed paper and expensive ribbon.
Or, to put it another way, Quicksoft made their money by having a relatively feature-full product which was nearly impossible to use without documentation. And people have been mistakenly trying to copy his success by utilizing the same technique, ever since.
Why did WordPerfect lose out to Microsoft Word? It wasn't because WordPerfect didn't already own the market; it did. It wasn't because Microsoft Word had more features; it didn't. Was Word a lot better, intrinsically, than WordPerfect? It actually wasn't.
Frankly, it was because of the F1 key. By the time WordPerfect got around to deciding they needed a "Help!" key, some of the function keys were already assigned, and so they assigned the next available one to be the "Help!" key. It helped sell a hell of a lot of keyboard templates. And it hid the help from anyone who'd experimentally go looking for it by hitting unlabeled keys in order until they found it (in fact, this would totally screw you up in WordPerfect).
Microsoft hit on a UX innovation: when something goes wrong, make the "Help!" key the first key someone is likely to hit, before all other keys.
And then they did it one better: The F1 was assigned to be the "Help!" key in *all* their products. Instead of just being a great UX thing, locating the key where they did on the basis of probability, they turned it into a Schelling Point: anyone who wanted "Help!" in any Microsoft product knew where to go to find it, if they had ever used some other Microsoft product, and needed "Help!" there.
So back to the original question: should you invest in documentation? Well, yes... if your product has already failed to the point where it's nearly impossible to use without documentation, or because, like Bob Wallace, you intentionally made it nearly impossible to use without documentation because that's one of the premises of your business model.
Maybe you want to write books on your project, once it's used by enough people to make that profitable, and that's how you plan to turn your hobby into a vacation fund. Or maybe you want to get to be a published author about a product so you get hired as a tech writer somewhere, or you get a lot of speaking engagements, and monetize your efforts that way. But if making your product hard to use was one of your initial conditions, then I think your software is broken.
Re:False dichotomy. (Score:4, Interesting)
Invest in both.
Fuck no.
Documentation is worthwhile.
UX is willy-nilly bullshit 99% of the time that you'll have to revisit over, and over, and over with each new fad. Any changes to "UX" shit will also force you to unnecessarily rewrite half of your documentation.
This. Documentation will tell people how to get something done. UX will just waste time and money.
UX is a bullshit field that is completely unrelated to HCI/HMI (the proper science behind how people work with computers and interfaces) made up to justify some companies incredibly crappy GUI.
If your interface is not user friendly, make it better but dont rely on pseudo-scientific quackery like UX to tell you anything, especially anything remotely useful.