Ask Slashdot: Should You Invest In Documentation, Or UX?

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?"

Comments

False dichotomy.

[aeschinesthesocratic]

Invest in both.

Re:False dichotomy.

[ShanghaiBill]

Invest in both.

You should go into management. Then you can bring world class excellence to any organization, simply by making everything a top priority.

You're doing it wrong.

[seebs]

If you have to rewrite all your documentation, you've done something horribly wrong.

Suggestion: Consider focusing on stability for a while, because stability is a huge win for user experience.

Re: You're doing it wrong.

[fpodoo8256]

We actually have four documentations: developers, community (how to contribute), designers (how to develop theme), users (accountant, crm, point of sale, ecommerce, ...) The first three are stable enough and we will for sure invest in a great documentation. But the latest, the business apps, will evolve a lot in the coming months as they are plenty of areas to improve. My question relates only to the user documentation. For developers and designers, we more or less freeze the api/interfaces.

Re: You're doing it wrong.

[seebs]

I am pretty sure that that is exactly the wrong thing, then, because the entire point of "business apps" is that people are supposed to be able to build a stable operation on them. If you are changing things so much that you have to rewrite the documentation entirely, that means you are changing them so much that anyone using the software must completely redo their entire process, retrain anyone using the system, and so on.

That's way too much change. If you are changing things enough that you are rewriting documentation every release, then you are not "evolving".

Re: You're doing it wrong.

[BaronM]

As an admin/IT manager, what I'd like to see is:

1. Meaningful, specific error/log messages when something goes wrong.
2. Accurate documentation of what those errors mean.

Most end-users won't read long or complicated documentation, business application in particular almost always require end-user training on how to use them --as implemented-- and --in accord with company practice/policy--, so generic docs are of limited value.

On the other hand, I sincerely miss the days when I could actually expect proper error codes and documentation thereof, and having that available would certainly influence a purchasing decision on my part.

Re: You're doing it wrong.

[ravyne]

Having a well-thought-out, consistent, orthogonal, and to-the-extent-possible obvioius UI can go a long ways toward the user experience, bring relevent information nearer to the user, and even make the documentation easier to write -- but even having achieved that ideal, UI/UX cannot and will not substitute for documentation.

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.

Not all documentation is giant documents

[penguinoid]

Have every menu command give it's keyboard shortcut, either next to the item name or as a tooltip. This is superior to a giant list of keyboard shortcuts. Wherever you can eliminate documentation by improving the user interface or integrating the documentation with the user interface, do so. However, there are some things that simply belong in separate documentation.

Open Source It

[Anonymous Coward]

And just make a wiki and the community will do all your work for you.

When every feature undocumented

[sinij]

When every feature is undocumented, how do you expect to attract new users or introduce new features?

Plus, there is no such thing as intuitive GUI, the best you could possibly do is to have shallow learning curve.

No doc

[Oligonicella]

As a developer and a user I absolutely *hate* apps with no documentation. None of the apps I see on your linked page are primitive enough to stand without. Actually, nothing more complex than say... well, nothing.

Functional spec

[mspohr]

Back in the very old days when I had a software company, we wrote detailed functional specs and used these as the basis for the documentation. It's much easier to go from a good functional spec to documentation than start from scratch. It's also a good test of whether or not the software works as intended.
I don't know if people still do that. It seems most software these days either copies some other product exactly or it's just the whim of the programmer.

UX? Meh. I have enough experiences in life

[caseih]

All this talk in recent years about UX as in "experience" drives me up the wall. Talk about euphemism! Why can't we go back to calling it what it is: user interface?

Mod parent up!

[khasim]

As an admin/IT manager, what I'd like to see is:

1. Meaningful, specific error/log messages when something goes wrong.

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.

Any software requiring documentation is broken.

[tlambert]

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.