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.
If your target market is not computer literate, than you either need to offer classes in how to use it, or a good manual.
excitingthingstodo.blogspot.com
It's much more Web 2.0 to create a user interface that's minimal to the point of being cryptic, and to call users that can't figure it out idiots. It also helps to have a complete lack of standards.
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
Unlike good code, good user interfaces are not self-documenting.
If it does come to cases about raw budget and manpower, get the head of the support department in your corner. Have him bring a couple of his best and or most experienced minions with him too. Regardless of how good the user interface is, they will be bearing the full frustrated weight of clients asking how to do things. For him, every man-dollar spent on the user interface that was taken from the documentation will mean upwards of 10 man-dollars that he will have to spend supporting the clients.
I'm not aware of Odoo, so I'm only speaking generally, but generally speaking, having a simple/intuitive product does *reduce* the need to documentation. For example, I don't need documentation to tell me that I can open a Word document by going to "File", selecting "Open", and then going to "Computer", "Browse"....
Now, come to think of it, the process for even something as simple as that has gotten needlessly complicated. WTF is Microsoft doing these days?
Back on subject, yeah, if you open files by going to an obvious menu button that says, "Open File...", then I don't think you really need to document that. You only need to document the features that aren't completely blindingly obvious.
The need for documentation can also be reduced by having a good help/support system. If you have a procedure for doing something unusual and complicated that's undocumented, you had better have someone standing by that I can call/chat/email who can help me out. And even still, that stuff should be documented at least well enough that you can train your support staff.
If you don't have good support and something is not completely obvious, then yes, it should be documented.
I currently manage a multiple websites spanning 17,000 pages using a custom written CMS (I wrote) used by hundreds of people. There is no WAY to manage documentation for this that no one would read anyway. Instead I put tool-tips all over the place and have a built in system to manage these as the system changes. Part of the development process is to update these when that section/field changes. It takes me a few seconds to do so and there is no need to create documentation separately.
You could adapt this methodology in your system. In addition allow certain user levels to add their own "enhanced" documentation to the tool-tips.
Here's how my system works. The tool tip pops up in a overlay and I they can edit it. Not only does this allow for crowd source documentation but the ability to add in business logic that defines the process. In fact administrators can update these on-the-fly by clicking "edit". Since I implemented this I've had 0 help requests for how to use the system.
This is a great topic and immediately grabbed my attention. A lot of it has to do with your resources. As an indie developer for the past decade, I've been working on software products in an DevOps environment as the sole employee. It's tough to keep on top of everything. Development, IMHO, is the most important thing as in a way, it's also your best marketing (a continually updated product shows a vested interest). I've been fortunate in that my software targets technical people (for the most part), but corporate environments can also very old-skool and like PDF and "manuals". To that end, I've started to use wiki-like blog postings to help describe UI elements and program functionality. With Wordpress and like products, it's very easy to put together a quick document with images/text and then link them via a "Help" button in the UI. There's an adage of the "cockpit test", if your software looks like an airplane cockpit, you should look at redesigning the software. There's also "people don't read documentation".. personally, I choose to spend my time in the UI and supplement it with quick documentation. I'm by no means perfect, and I have a stack of things to document via this method; but my hope is that I can stay on top of the UI work and allow that to answer my questions... then again, perhaps I'm old-skool and what I like is perhaps "dated" looking.. I use the hell out of the WinXP graphics pack from Glyfx (https://www.glyfx.com/shop/listings/xp-icon-sets/)
I made this: http://www.bpftpserver.com
Having written lots of software documentation in the 90s and developed numerous UIs since then, I've come to use a balance of UX and documentation. My strategy is to build into the UI simple instructions for operating each set of controls encountered by the user. Often these instructions appear in info panels that the user can dismiss when they no longer need/want to see them. The documentation then becomes little more than an outline of common and advanced procedures the users may perform within the app with short instructions of where to begin the procedure within the UI. So essentially, the documentation acts as an easily navigable directory of procedures, and the UI provides the step by step documentation within info panels.
Do you know any complex software that succeeded in avoiding documentation by having significantly improved usability?
No. I have worked with software that has tried.... there is nothing more annoying.
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?
Sometimes simpler is better, but if it's simple enough to not require any documentation then it probably will not meet the users needs.
Sorry, did you want a serious comment? Oh, you want the Serious Comments Division down the hall...
If you need extensive documentation... you had failed.
Do you think we can get away with being incredibly cheap and not wasting money on writing documentation?
Honestly, write documentation. Only the scummy companies dont.
Do not look at laser with remaining good eye.
You can coordinate with third parties to create multi-level documentation. This has been done by many well used programs. It improves THEIR ability to provide documentation, creates synergy with others, and lets you focus on development. Spend your time documenting getting to the point of needing further documentation, let others provide it.
If you can't find others to do this, you may be finding that your whole thing may be a waste of time.
If nothing else, making documentation ensures that you get to check that your features are sane and make sense. Nothing like documenting something then realizing how stupidly it was written, then you can fix it so the documentation can be simpler.
From a user doc perspective, Apple Mac OS X is a great example of what you can do with a minimum of user documentation, but with very mature and fully enforced user interface guidelines. In fairness, someone new to the platform does need some hand-holding, either training (including over-the-shoulder help from a family member :-) or a good book (I'm partial to the Pogue "Missing Manual" series.)
From a developer doc perspective, if you expect to maintain the software, some amount of documentation, that should capture (1) interfaces; (2) design intent; (3) full build/reconstruction directions (including configuration data, etc) is essential. And "Agile" that ignores these documentation/sustainment issues is just an excuse for write-only coding.
Being able to articulate your decisions, why and how things are built is a core competence. You will "pay" for poor documentation. It may never show up as a line item, but it can be costly.
It also needs to be someone's job. Depending upon engineers or the sales guys to generate documentation, courseware and manuals is a fast way to jack up your tech support costs.
---- The above post was generated by the Turing Institute. Maybe.
That you would even ask the question "do we really need documentation" demonstrates that you desperately need documentation. You have no idea how users interact with your software (and all software).
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?
Instrument your documentation pages if they're online. Put high priority focus on the most used pages for your initial roll-out if that makes sense. Have your Product/UX team talk to clients and see if they find the documentation useful and make sure they have a decent quality sample size. Talk to customer support to see if customers are calling in with questions that was available or not available in the documentation. Measure cost to customer benefit and client retention and if you don't know how to constructively do that, don't change how you're doing things until you do.
UX is good, and you have to invest in it no matter what, but it'll never be a silver bullet unless you strip your apps way way way down - something that'll be painful for both you and your established users.
But if your docs really are a bottomless pit, it might behoove you to invest in your community instead of documentation. Grow some in-house experts and put them on the forums and a chat system. Send your users there instead of to increasingly out-of-date help docs and get them in the habit of searching for answers there. Build a reputation for responsiveness to get free customer loyalty on the side. Send your UX people and engineers to the forums as well so they get the pulse of your most frustrated customers. Slowly your community will become your experts as well.
Should You Invest In Documentation, Or UX?
Yes.
So, I guess first off if your product is open source, do you have customers or do you have users?
Second, say I'm evaluating a new product, and I stumble on yours. After looking around I conclude there is no documentation at all.
Now, do you think I'm going to download and install your software so I can play with it and see if it might possibly be useful for me? Or am I going to look at the absence of documentation as a sign that I should look elsewhere?
My honest answer, is I'm going to assume you're like every other open source project with no documentation and keep looking. Because it smacks of either amateur hour, or the bad old days of open source where all you got for help was "RTFM" (which in this case there wouldn't be), or "figure it out for yourself".
If you've got 250 apps with no documentation, what you have is a sea of unintelligible stuff which nobody is going to want to get anywhere near.
And if this is supposed to be a business suite, how are people going to pitch it to decision makers when you say "um, well, there's no actual documentation". If any business lets their IT folks roll out a project based on software with no documentation, they'd be complete idiots.
If you're not documenting it, people who aren't already users of it will never use it.
And, really, 250 frickin' apps without documentation?? Yeah, no.
Lost at C:>. Found at C.
The only intuitive interface is the nipple and some babies still mess that up. Everything else is learned.
Documentation is necessary. Don't skip it.
Having written 1000 page tomes of technical documentation for my company's product API's (many of which I wrote) I can relate to your conundrum. These days there are tools that can take embedded documentation from source code and if it is written properly, generate at least a good portion of the documentation needed (JavaDocs, etc). However, this requires some real discipline in the development team to write good (and complete) inline documentation, which is where it really should be sourced from. The development team knows what is intended by the code and API's, and can fill in some other information, such as the rationale behind certain constructs that may not be obvious on the face of it.
In any case, such tools w/ embedded documentation strings can reduce the amount of work to produce a final document product that will be usable by your customers. These can also be put online for web viewing, wikis, etc. In my case, I have always felt that too much inline documentation was far preferable to too little. After all, I may have to go back myself to do enhancements, bug fixes, and such and this helps me recall why I did what I did.
You can skimp on documenting the obvious.
You can delay documenting the obscure, or even leave it undocumented as an "easter egg."
Anything else I would expect to be well-documented OR I would expect the product to say, up front, that its documentation is sparse.
Have you considered making bare-bones documentation in the product and making the full documentation a community-driven project, perhaps a Wiki? Now that the base Wiki software makes it easy to have "pending edits" which are not shown to non-logged-in users, you can do this without as much of a "troll/vandalism" risk as in the past.
Knowledge is how to play a game, intelligence is how to win, wisdom is knowing what game to play.
Sounds like you have bigger problems than your documentation and user interface....
---- Booth was a patriot ----
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.
Although their are plenty of books written by others to explain them. There's an analogy in there somewhere, it's not car analogy, but even automakers let Chilton's write their documentation. So, the answer is no you shouldn't waste your talent on scribe work if you are a genius.
Alternativley, if you need to explain what your program is doing to someone who presumeably bought your program with the expectation that it accomplishes their intended purpose, then maybe you aren't a genius after all.
I thought modern software development is documentation free, which is not to say that documentation is not needed, it is just not done.
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.
Trying to eliminate documentation would be a mistake, since there are few interesting applications more complicated than tic-tac-toe where one UX would satisfy all (or even nearly all) of your users. Some of us understand visuals more readily than text. Some want advanced features to be readily available while others find it confusing when advanced features are as available as those a novice user would need. How many, and how detailed are your user models? The "ideal" experience is varies from one user to the next. Documentation is one way to satisfy a wider range of users.
Your question also causes me to believe that you can improve your team's overall productivity. Ideally, your UX does not change significantly from one year to the next. If it normally does, you are placing an unnecessary learning curve burden on your users. In that case, you need to improve your understanding of the users, and work hard to create an experience that can scale as the product features and user expertise grows. This is easy to say but not necessarily easy to do. The better your user models, the more likely you are to create a UX that really works.
Another question that comes to mind is whether or not you are making effective use of context sensitive help. Again, depending on the complexity of your application, context sensitive help can play the role of many types of documentation. It can also be easier to reuse. Looking at it this way, effective documentation is a part of the UX, not separate. As such, your documentation needs should only be significant when market and/or the product roadmap justifies it. For example a shift from predominately desktop/laptop users to mobile/tablet users might justify major UX changes.
Hope these thoughts help.
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.
Generally, for a given operating system you try to make your software so that it functions in similar ways to other software. That way, in order to use an app a lot of the fundamental things are trivial. Whenever I've written apps in Windows, for any particular function, I look at how another app accomplished the same task and made mine work like that. A user should be able to perform basic functions of an application without going to the documentation.
Having discovered Odoo within the past few weeks, I am in the process of wrapping my head around what it can (and cannot) be used to accomplish. I think it might just be the *next big thing*, and of course I am partial to the python+postgres backend, the contemporary bootstrap-integrated frontend, and the sense of an open source community with thousands of users and hundreds of developers. This could all be very disruptive to Microsoft-as-a-platform (tm).
However, I cannot be the only new user who has become drunk on the MARKETING for the latest online-only version ... and then WHAM! Where is the documentation supporting all of these amazing features? As a potential customer (one who cannot use the online version and meet regulatory compliance), I need to reach a conclusion on the true capabilities of this product -- and to know when to cut losses vs push forward to implement specific features. Github is great, but I don't have the time to examine 200k lines of code and templates as a substitute for introductory tutorials, howtos, and general documentation matching the current version. It does not help matters that many of the thousands of available modules appear to be out-of-date, the documentation I have seen for previous versions is scattered among various sites and formats, and the help forum is heavily populated with unanswered questions that might have been avoided with better docs (or better navigation to existing docs?).
So .. I will keep plugging away trying to make sense of it all, and eagerly await the official release of the new version 8.0. I anticipate improved docs will bloom from the community at that time, as well as traditional publishing. To answer the original question: I would prioritize UX over DOCS for the primary development team, but also feature freeze and release on schedule, provide basic (core) documentation, and provide a stable platform for the community-based documentation to take root. And finally, when great documentation is available, please link to it from the marketing page for each amazing feature!
Yes - an obvious UI should reduce the need for documentation. Are you documenting every single screen - and is it really useful?
We split everything into a few buckets:
* Proper and Intended Use of the product
* End User Training
* Suggested workflow and use (kind of a how-to accomplish important tasks)
If users are unable to accomplish their work without reading the documentation - then there is a problem. Our documentation went down from "feet thick" to a small "1 cm thick" manual. Via a removal of duplication and splitting into Role based helped keep changes to a minimum.
Of course - if the UI is changing that drastically every year - are the customers happy? It sounds like there's a huge investment from the customer base to re-learn the product every year. At some point I'd get tired of that and slow down how often I upgraded...or went looking for a less complicated product.
To answer your general question: Yes - it is possible and you will be successful in doing it.
Wider question, not asked but we all derived, it sounds like some change control needs to happen.
Good luck.
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.
Both?
Windows has always been a complex piece of software that shipped with virtually no documentation.
It seems to have done quite well despite.
Project work isn't just about coding. You shouldn't wait until you're entirely done with a big piece of the project to adjust all the documentation. Like anything, it should be done in increments. People can't effectively use an application with proper documentation nor can they use a well documented piece of junk software. When developing, you have to weigh the cost of each of these and try to do them at least reasonably well. But you can't just have one, nope nope nope.
This isn't done all that much but systems like Knuth's cweb might come in handy here?
Possibly of limited use in user documentation but could lighten the load for the
developers documentation, especially if it's a small core of developers.
Might need to involve an editor though.
Send your source through one filter and out comes a program,
through the other, the typeset documentation. The source includes both code
and the relevant documentation is near the actual code.
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.
I'm guessing that there aren't a lot of people on Slashdot who are both users and developers for Odoo / OpenERP. I am. I am also formerly a UX expert (late 90's, but I keep somewhat up-to-date), and I am currently an active developer and consultant. I have some very specific views on this based on my background.
1. In the Agile manifesto it says "Working software [is valued] over comprehensive documentation." That has always meant, to me, that UX takes priority over user documentation. I've seen Agile teams kick the snot out of competitors by focusing on UX and foregoing nearly all user documentation. When I say "nearly", I mean that a very high level (well written) orientation document, is sufficient.
2. For this system itself which is a complex ERP system, there are four levels of "documentation" possible: a) User Documentation b) Configuration Documentation c) Customization / Plug-in Developer's Documentation and d) Internal Development Documentation. Since Odoo is open-source, in a way, all of these levels are "user documentation".
3. UX absolutely needs to be the one and only factor in considering the end user experience of an already-configured system. There shouldn't be any need for an end user to go to a user manual unless an organization has done extensive configuration / customization (in which case that organization has the responsibility for the documentation, not the Odoo organization. Likewise, UX should be the main approach to making configuration easy, but there may be some scenario-based examples documented to help orient those who are doing the configuration. These are your day-to-day admin users. The marketing automation module is a good example of where UX sucks and the documentation is poor. Given the choice, I would much prefer the UX to be improved!
4. For customization and internal development, there is still a role for UX to play, but (knowing the actual state of the documentation) you must improve that documentation dramatically. It is sparse and hard to follow, hard to find the right information, and often has very old / outdated screenshots. Although what information there is seems to be accurate, there are often huge gaps, and many undocumented api's and options. I know this because I have had to struggle through creating custom modules by reading through reams of source code in other modules. Love that it's open source, hate the quality of the developer documentation :-)
As a sideways promotional plug, our Scrum Team Assessment tool is built on OpenERP 7.0.
Helping with organizational effectiveness is our job.
This should not be an either or discussion. As new features are being developed, there should be a resource tasked with leading the documentation team and ensuring that they stay up to date with the feature changes. The resource needs to be technical enough to listen, take good notes, and most importantly, understand what the developers are talking about during the change meetings. Conversely, the developers need to be available to that person and their team when additional clarification is needed. That will slow the developers down a little bit, and we all know how much developers hate having to explain what they do... but in the long run, the product will be better for it and the team will be better for it.
Hi Fabian o/
many of the modules have really really little documentation, just a fairly small description string in the __openerp__.py file. It is great that this is now in markdown format, but they are nowhere near long enough in the modules. I would like to see each and every module being like a chapter of a book. If you take it out of the __openerp__.py file and move it to a README.md in the module then it would also render on github I think, people could then use screenshots and so on in it. This would also separate documentation updates (easy and safe, nobody should be scared, can be done on github with the github markdown editor) from editing a .py file with potential for breakage.
In terms of how the documentation is written, some modules like CRM use the description string to sell the module to you, others use it to describe what it does, I don't really need the sales pitch, but I do need to know what problem it solves, and what kind of business situations that the author had in mind when it was written. Plus of course, what it does, how to use it and anything it conflicts with, any downsides to installing it.
So I just checked out this SaaS site and it looks like they might have some tools that would help you:
https://www.odoo.com/page/community-builder
https://www.odoo.com/page/discuss
https://www.odoo.com/page/survey
You should check them out.
I made an application for myself to record audio and decided to sell it. Soon professional sound engineers where buying it because it did one thing well, record audio. You'd be surprised at how bad most audio recording application are with that simple task. Which is why I made my own.
The design of the user interface exposes how the inners are actually working. My customers like this because they know what happens when they press buttons, etc.
But I also made mistakes by using user interface elements from other applications. Which made it complicated for both me and my customers, I've since changed it to match the underlying application, and customers and myself rejoiced.
In designing your user interface be true to the underlying application.
Atleast reads like it.
Good UX can (and should be applied) to your documentation as well as the full experience. Wikis and forums can go a long way to help customers, but are not a full solution. It might be good to take a few steps back and list out the places where your customers can learn about how to use your software. Then intentionally decide where they *should* be using the software.
Another route for this--or perhaps a supplement--is to find a good user researcher and ask them to poll users for experience gaps. (Easier said than done.) As another poster mentioned, it's better to narrow down on the things that will help most instead of trying to make everything a priority.
All the best--and remember the docs are part of the product. I often here people poo-poo the docs. They are wrong.
Form an executive committee to create a taskforce to partner with a strategic consulting firm to build a magic quadrant of developing best practices in this area.
No one reads documentation.
When the UX fails, the role of documentation is to be there to prevent the user from quitting in frustration (and turning to a competing product).
I do think a rich user community forum and/or wiki can supplant most of the need for documentation (e.g. most open-source projects), however, all features of a product should have some basic documentation (e.g.: command-line usage --help).
Extensive documentation adds a lot of "drag" to a product - this is both good and bad, but where doc can't be updated, the user should *at least* know how stale it is.
Make sure everyone's vote counts: Verified Voting
Great UX drastically cuts down on the documentation required by the end user.
You have a problem. Hit F1. Long wait. Then you get a generic help file that has 99% obvious stuff. The answers I want (what does error 99394A33 mean?) are on Google, never in F1.
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.
Docs are code for people. Our build system generates both API documentation and end-user documentation based on decorations in our source code. For the end-user docs it also has a robot that is scripted to visit screens; enter text; take screen shots; crop images to particular controls, groups or regions, etc.
When ever I am required to make a product selection comparison, possibly the most important factor is good documentation, if it doesn't have it, it won't even get on the the short list.
"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?"
I would say if you believe you have a programming team full of programmers that can reasonably judge what end-users consider "simple" in terms of usability, you're either the luckiest dev team in the world to manage to catch such incredibly rare people or you believe in Big Foot.
I once encountered an entire room of end users who honestly could not identify the space bar on their keyboards (being people who had no previous experience with computers or typewriters). Most keyboards don't label the space bar. Your target audience may not be that inexperienced, but without documentation I can guarantee most will be unable to figure out how to use your product and will switch to one they can figure out - because there's good documentation or online help to assist them.
Usability is not the most important thing, its the only thing. It doesn't matter what software does. It only matters what the end users can make it do. If the end users can't make it do a thing, it doesn't matter that it can do that thing. And its never the end users fault, even when its the end users fault. Because they are the ones that get to choose which software they buy and use, and they will choose based on what they can make it do. Consider this when deciding how important good documentation is.
OpenERP!!! It is no wonder you rewrite your documentation with every release. Odoo/OpenERP change their software making it INCOMPATIBLE with previous releases ON PURPOSE. These guys asks for money AND YOUR DATABASE to make upgrades.
Odoo/OpenERP you can go away, no one will ever miss you.
If writing (or getting people to write) user documentation is hard, perhaps you can put together good video tutorials on how to use many/most/all of the features in each module. You can even get developers to actually do the video demonstrations, because it gives them a chance to show off their cool new accomplishments. You can probably get people to do replacement narration as well, both for developers who don't do a good job narrating (language issues, accents, mush-mouth mumblers, etc.) and for alternative languages.
Put those videos up on Youtube or Vimeo, perhaps even annotate them with links to the official docs (such as they may be), with notes about features not demonstrated in that video, or with links to related training videos.
Then you can point to those videos not just for training materials, but as marketing/demo items.
fencepost
just a little off
It probably is bullshit if you base it on fads instead of on end user preferences. One solution is to look at the the really successful sites, and see what you can do with a multi-million dollar budget. I suspect you will mostly find designs that follow the KISS principal.
I would favor user interface: it is easier to add missing doc afterwards than fixing a bad UI.
I just went to the odoo site. I happen to be in the market for an ecommerce platform for my growing online retail business.
I'm seriously considering Foxycart, Avactis and Ecwid. Might as well consider Odoo, since I know what others are offering.
But Odoo's online documentation is an utter mystery. No documentation on what it does, how to integrate, what the per-sale / per customer costs are. Nothing about a PayPal API, let alone an API for Authorize.net or maximum number of products. They say $15 per month per user. Does this apply to me when I'm handling 2000 sales per month?
Lots of empty verbiage and overuse of the word Awesome: "Odoo's e-Commerce software is unlike anything you have ever seen before. Get an awesome catalog of products and great product description pages."
So I try setting up an ecommerce system -- I'm funneled into "Set Your Accounting Options" They're advertising e-commerce and their website directs me to accounting. Sigh...
Obvious questions are unanswered by Odoo: What will my business model be (self-hosting? Cloud hosted? Odoo hosted?) What do I add to my website for a checkout? Is there a checkout? Does Odoo host my website or just the checkout?
After spending 20 minutes playing with it, the Odoo system feels like an undocumented fuzzy dream. Good luck to 'em. I'll take my business to someone who can handle my e-commerce needs. At the moment, we're leaning to Foxycart. But Ecwid is a close contender...Clearly Odoo is dead in the water.
UX has only ever made software _LESS_ usable. Good luck if you go down that road.
It's OK Bender, there's no such thing as 2.
GMail is a good example of an interface that you don't need to read a user guide first for --- although they do have short articles for those who get stuck. Google in general does user interfaces well. I credit it to: (1) using one-word, plain-English text labels instead of icons (or at least they used to), (2) clean and simple layout (which, by the way, is anything but simple to make) and (3) just a thousand little things to make the user's life easier. For example, while most email programs showed just the subject in the list, GMail showed as much as the message as possible. After all, people are bad at writing subjects. Little things like that, a hundred times over. There's no one big thing that turns it from a bad UI to a good one. It's just lots and lots and lots of polishing.
37Signals at least writes about what I think is the most efficient route to good software. See their book, Getting Real. I haven't used their software much, so I don't know how well they execute, but lots of people like it.
I think you should major in UI and minor in documentation. I think you will always need some documentation. And maybe your software needs a lot. Some software does. And a few of those projects have outstanding documentation. I don't know, see how PostgreSQL keeps theirs up to date.
1. Integrate the documentation with the application. Treat it like code rather than as a separate document.
2. When new features are proposed, plan them by FIRST forking and changing the documentation, THEN implement the change based on the change in the story. This not only guarantees good documentation, it ensures the developers are all on the same page about what the changes should/shouldn't do.
3. Focus documentation on the common tasks, software limitations, and side-effects. Far too much documentation wastes reams of paper telling people "to create a new widget, click the New button." If the "New button" is hard to find, difficult to click, or does something other than creating a new widget, that is a failure of the UI, not the documentation.
"Do you know any complex software that succeeded in avoiding documentation by having significantly improved usability?"
Yes. Android.
"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?"
Fine, as long as it hand-holds the user right at the beginning with some simple (possibly animated) guides.
Garry Knight
Don't invest in UX. Invest in UI (user interface). The rot really started when this whole "user experience" fad began. If a user interface is giving me an experience, it is a bad user interface. User interface should melt into the background and explicitly be designed to NOT give the user "an experience".
Please don't continue with the "user experience" bullshit.
Oolite: Elite-like game. For Mac, Linux and Windows
Then you end up with a massive pile of disorganized crap written in a thousand different voices for a thousand different audiences. If a company can't be bothered to hire a good technical writer to create an organized, consistent documentation system then I am not interested in their product. If a FLOSS project can't/won't attract the same, then I figure their product is probably crap too.
If you truly believe your product is good but you won't invest in good documentation, then you are (at the worst) signing your projects death warrant or (at the least) "hiding your light under a bushel" and drastically limiting its success.
Even if a FLOSS project doesn't pay a single developer, if it can't attract a good technical writer then it should hire one if it ever hopes to really be taken seriously. Even if all those developers are just doing it for practice and don't expect to commercialize the project at all, good documentation will cause that project to rise to the top and really help build the professional reputations of those developers.
It's always there and easy to find, people know how to read the docs, you get more bang for the buck with docs that actually TELL the reader what they need to do.
- Zav - Imagine a Beowulf cluster of insensitive clods...
For the Support Person
My experience and my position about documentation management is to put the documentation into the source code. In this regard, I use doxygen and use it to scan source code documentation headers. Not all functions need documentation, but the critical ones do. Don't want doxygen, use whatever you like, as long as documentation is within the same source file that it is describing. Nothing is worse than completing some source code, and then having to start over again to document with a word processor, when both development and documentation can be done concurrently.
Where the documentation has to be the user interface, I would still use doxygen for each window. And if the Window or function changed, the documentation header would be revised.
Finally, I would also create a very few narrative documents to cover more of what the end-user expects from the application.
Leslie Satenstein Montreal Quebec Canada
Because if the user experience is good enough, documenation is moot.
As everyone knows, having the letters in an acronym actually match the first letter of the word they stand for is stupid, so you should invest a very large amount of money replacing every instance of "UI" with "UX".
I honestly can't remember the last time I read software documentation. API docs, yes; functional specs, yes; but documentation for an application with a user interface? Wow. No.
--- SER
This is something that the OSS community still struggles with, work on UX. We have video tutorials, documentation, mailing lists and other forms of support coming out our ears, but the UX on even some of the most popular OSS projects is atrocious!
What would be great is if there was a community project to define a UX methodology and design language that can be easily re-used across OSS projects (along the lines of Google's Material Design). More importantly, great effort should go into getting the best talent involved in this. I suspect that a lot of UX work done in the OSS community today is not done be real UX experts (being a Gnome or KDE developer does not make you a UX expert, UX is about understanding behaviour, knowing how to research and test, and understanding how to quickly iterate based on prior research and testing).
The Manual (PDF) Opens in your Browser
Unless the user has disabled Adobe Reader's web browser plug-in to avoid exploits of vulnerabilities in said plug-in.
NEVER assume anything
"Never" is a strong word. For the vast majority of personal computer applications, the developer has to assume that the user can read and write. The question then becomes where to stop assuming common knowledge.
For example, I don't need documentation to tell me that I can open a Word document by going to "File", selecting "Open", and then going to "Computer", "Browse"....
You'd be surprised at how I have to walk an older relative through everything every single time. Even with a big green "Begin" button on a web page, she freezes up unsure of what to do and calls me. When she enters a search query or a URL into Chrome, I get asked every time: "Do I use capital letters? Do I use spaces? Do I use dot com?" And when searching the web, she always has to ask me for what words to use in queries (and "Do I use spaces?" again) and then ask me if everything is correct before pressing Enter because she has no self-confidence in her computer skills. "I don't want to learn; I want you to make this bookmark for me." God help her if I happen not to be in her house at a time, as she postpones things for days until I visit.
the worst of all is "You are unable to log in at this time. A system error has occurred."
Sometimes the vagueness is intentional to protect your account from intruders.
How would, say, a web browser be made self-documenting? I've seen people get confused as to what a URL is, whether they need capital letters, whether they need spaces, whether they need .com, whether to put a particular thing into "that bar at the top" or the big "Google" search box on the home page, etc.
Put those videos up on Youtube or Vimeo, perhaps even annotate them with links to the official docs (such as they may be), with notes about features not demonstrated in that video, or with links to related training videos.
YouTube maybe, Vimeo no. Its policy forbids "Product demos and tutorials."