Slashdot Mirror
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?"
en tee
Hail Eris, full of mischief...
E pluribus sanguinem
Invest in both.
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.
My blog: http://www.seebs.net/log/ --- My iPhone/iPad app: http://www.seebs.net/seebsfrac/
No one reads documentation.
I hate sigs.
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.
Don't waste your vote! Vote for whoever you want, unless you live in a swing state it won't matter anyways
And just make a wiki and the community will do all your work for you.
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.
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.
SJW's don't eliminate discrimination. They just expropriate it for themselves.
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.
If something is an end user product, it appears to be sad but inevitable that nobody RTFM anyway, so you are probably better off doing everything you can to make it actually work when prodded by the clueless. Try to make sure that it's all point-and-drool simple(if it is possible to back yourself into a 'mysteriously doesn't work, provides meaningless or nonexistent clues as to why' corner; an elegant way to roll back is nice).
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.
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.
I don't read your sig. Why are you reading mine?
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.
Persistent Volume manager for Kubernetes - https://github.com/dwimsey/openshift-pvmanager
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?
Do you know any complex software that succeeded in avoiding documentation by having significantly improved usability?
To answer your direct question: Yes - Games regularly do this, because no one reads the manual (if they even have one).
That said, no one reads any manuals until they get stuck. So realistically, time invested in useability will provide far, far more benefit than time spent on a book that never even gets opened.
However, games have the rare luxury of forcing you to play a tutorial when you start. As much as I wish I could force most of my coworkers to "play" an Excel tutorial every time they start a new spreadsheet, I doubt "serious" users would have the patience to put up with that level of handholding (even when desperately necessary).
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.
Just as there is no such thing as absolute security, there is no such thing as a 100% intuitive and self-documenting UX.
No matter how simple or complex software is, there is a limit to how much "help" the UX can offer. The UX should have enough hints/labels/tooltips/etc to keep the user from getting lost performing light to medium tasks, but inline is not the place for describing complex workflows, data structures, APIs, or other heavy topics.
Documentation is the ultimate resource for the users, most documenting elements in the UX should be considered a convenience. The phrase "RTFM" exists for a reason, there is no "RTFUX".
It also sounds like you're handling your docs wrong... they should evolve with the codebase and not need a complete rewrite for every release.
Make the Apps self explanatory, use mouse overs and build in help. Code so that the developers have to write the code and the build in help same tim, after all the build,in help should come easy from the story/use case descriptions. ...
Oh, you neither use user stories nor use cases, see headline
Cost free eBook I read (by iBook/Kobo/Amazon/ObookO/Gutenberg etc.): "The Green Odyssey" by Philip Jose Farmer.
I've used the software, it was OpenERP in its previous incarnation. I've ploughed my way through the developer and user documentation.
The documentation is abysmal, much of it is not updated between versions and can refer to settings, functions, etc that no longer exist. In some cases I've seen it refer to whole sections that no longer even exist like report design and outlook integration. There are numerous places where it refers to things that do not exist unless a specific module is installed but at not point does the documentation ever mention that the module should be installed.
On the developer side, there appears to be much that is broken by design rather than by error. For what is supposed to be a piece of critical business software, the inability to do something as basic as a bank reconciliation and print off an aged debt report out of the box is unbelievable.
Perhaps working on the core competencies of the software instead of diverging into including web site builder and CMS systems ? Your product can't do something as useful as calculating the cost price of a Bill of Materials assembly, so get the basics working and documented clearly before you do anything else.
At very least, start documenting new stuff via a wiki, before new commits get integrated. Better yet, documenting a new feature BEFORE coding it can increase quality and reduce development time by causing developers to think through the user experience before implementing something.
We also have our support and and customer service people copy/paste emailed answers to the documentation wiki so they aren't typing the same thing repeatedly and the information can be found without emailing support in the future. That doesn't require writing any more documentation, just copying and pasting info you're already writing.
If you need extensive documentation... you had failed.
At Kandy Krush perhaps.
At a real program, not so much.
Faster! Faster! Faster would be better!
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.
I support a lot of apps... some with lots of documentation, some without.
If management came to me an asked me to assure them that your application was secure enough to store sensitive data in it, and you had no documentation... how could I assure them of that? Does the application calculate financial data accurately? I don't know. What's the developers long term goals for the product? Does it support X format? How far along is the API? Are they getting rid of it?
Documentation is far more important than just "How do I save a file?" Without it, most businesses will never approve your product for use because they'll not be able to get answers to whatever questions they need answers for to approve it.
Applications should strive to be "Self-documenting". The user interfaces should be self-explanatory. If they are understandable, the business using the app will in general be perfectly fine working out how to train its users about the proper use of the application.
But for a business application, you need good detailed administrator documentation, also; including technical design information and recommendations, which are needed to understand whether to use the application (or something different) and how to appropriately design the deployment in a manner that suits the needs of the business.
If you can't bother to do that, then I, and other technologists will tell the business, that we need to buy a different product, because this one isn't adequately documented: which is a huge big red neon warning sign.