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

Yes.

[Nimey]

en tee

False dichotomy.

[aeschinesthesocratic]

Invest in both.

Re: False dichotomy.

[MrBingoBoingo]

And then there's the matter that a number of people who really benefit from good documentation are developers. Documentation helps describe to your team what these chunks of code are supposed to do and in the long run can help to avoid the problem where "new features" end up poorly replacing popular well used features.

Re: False dichotomy.

[Anonymous Coward]

"you're not wrong but you're wrong", ofc the manual should be userfriendly but even the best manuals are often ignored by the users, tests have shown that even with very simple (that is, easy to read, understand and apply) documentation, in a population you will find two groups of users - the group that understands the interface and uses the manual, and the group who turns to members of the first group for help at the slightest frustration.

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.

[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.

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.

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.

Every release is a rewrite?

[BitZtream]

Then you're doing the whole project wrong.

I'm guessing you've got developers with no leadership or plan and certainly no forethought.

You should invest in some project management and developers who are playing for the team rather than just writing what gives them a buzz that day.

No one is going to use your software if every release is so different that you have to rewrite the docs. People use software to get something done, not because they want to spend their time learning how you decided to rewrite it and do things differently.

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?