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?"
Yes. (Score:2, Insightful)
en tee
Re: (Score:3)
Hos this a Troll and the False dichotomy, which says the same thing, Insightful? ...
/ I know, don't complain about moderations, but some times
False dichotomy. (Score:5, Insightful)
Re:False dichotomy. (Score:5, Funny)
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.
Re: (Score:2)
It works for my company!
(well not really but they keep trying to make everything a priority anyway )
Re: (Score:2)
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.
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.
Re: (Score:2)
I think what you're really getting at is that UX should not omit attention to the UX of the manual itself.
Re: (Score:3, Insightful)
"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.
Re: (Score:3)
I would say however, that a big source of frustration for users when they need to dig into the manual is digging thru to find what they really want to do.
To which I add the caveat, if the documentation SUCKS , ie poorly written/laid out/indexed, it's an even bigger source of frustration. Like, "I would really like to throttle the idiot who got paid to write this offal, preferably with a Franklinator [youtube.com]" kind of frustration
Re: False dichotomy. (Score:4, Insightful)
Re: (Score:2)
I test with users for a living, and I agree that this is a false choice. You should have both. I would say however, that a big source of frustration for users when they need to dig into the manual is digging thru to find what they really want to do. The UX should support ease of use for most people. The manual should focus on everyone else. (Possibly supported by a quick-help guide for the really basic user.) YMMV
I have been incorporating "online help" available directly from the application. These "help" buttons are linked to Bookmarks in a MS Word -> PDF document that is located on an Amazon S3 Server. The nice thing is, unlike your typical "Help File", which tend to have "explanations" that are circular, or that refer to even MORE gobbledegook, this is the "real" documentation, "opened" to EXACTLY the relevant Page.
Personally, I think this is a much better alternative to a simple "here's your PDF, have at it
Re: False dichotomy. (Score:2)
To expand on your idea there... why not have it organized in a wiki, and link to the relevant wiki article?
I understand having an offline manual is a godsend at times, but I prefer an online resource vs a PDF. This is my personal preference, though.
Re: (Score:3)
I am not a big fan of having the primary documentation for a product off-site. Unless you take a lot of care to set up version-specific pages, people who are running an older version of the product end up reading the documentation related to the current version and get very confused.
A wiki has its place as supplemental documentation to answer frequently-asked questions or to help with troubleshooting.
Re: (Score:2)
See my comment above. We generate both PDF and HTML from exactly the same source. PDF sucks for online viewing, but it's great for printing. HTML is just the opposite.
Re: (Score:3)
We do something similar in our product. We use LaTeX as the source format for our documentation. This generates a very nice PDF for offline reading. It also generates very nice HTML using htlatex. Finally, we define custom LaTeX commands that link specific sections of the manual to specific pages in our web-base UI. So when you click on the Online Documentation link from any web page, you go exactly to the spot describing that page.
We also have custom LaTeX commands that expand to null commands when
Re: (Score:2)
And we have a winner!
Most hardware I buy these days comes with a quick-start guide to just make the thing work. It shows users the basic installation they need to get something working, so they can learn on their own. A well-designed product will encourage such self-guided learning, as it empowers the user.
However, not everything is suitable for a quick-start guide. It's not the right place for preferences, advanced settings, unusual configuration, or alternative use cases. That all belongs in the manual wh
You're doing it wrong. (Score:5, Insightful)
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. (Score:5, Informative)
Re: (Score:2)
If the UX is really good, you can let the user documentation slide somewhat. You can also think about presenting the basic user docs as a wiki and encouraging your user base to expand and expound on that. Editing user contributions will be a heck of a lot easier than writing from scratch (you can start things off by just publishing an outline of what needs to be covered).
Re: You're doing it wrong. (Score:5, Insightful)
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: (Score:3)
If by "plenty of areas to improve" they simply meant the documentation for business use, however, then it just means they need the docu
Re: You're doing it wrong. (Score:5, Insightful)
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.
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: (Score:3)
Many years ago, I did tech support for a small startup that used a proprietary database (btrieve, I think) as part of its back end. The developer who wrote that part would have the program show the user the exact error message returned if the database had a problem. Alas, not only didn't the messages make any sense to the users, they didn't make sense to me, either, and I wasn't given any access to the documentation, meaning that un
Re: (Score:2)
One of the benefits about the teams I work with is just that, we're TEAMS.
So if I'm working on my part of the project, and something breaks from the other teams and the error is non-obvious, a bug report is filed saying not only how the error was generated, but that the error message itself is not clear to me and needs to be fixed.
QA has also been trained just enough to know when an error message doesn't make much.
Re: (Score:2)
1. Meaningful, specific error/log messages when something goes wrong.
This, a thousand times this.
I hate meaningless error messages like "An error has occurred" but even worse are ones with cryptic codes like "An error has occurred. Error code:5" and there's no reference for error code 5 anywhere or worse yet, error code 5 has 15 different meanings.
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.
Re: (Score:2)
Having a well-thought-out, consistent, orthogonal, and to-the-extent-possible obvioius UI ...
DON'T rely on your own intuition about what's common or difficult for users, ask them or collect the data.
You have it exactly right, but notice the AskSlashdot talked about UX, not UI.
UI is a science, there are methods, data, studies and books. UI people are rare and valuable.
UX people tend to add more whitespace, transparency and animations, making the product look more fashionable (" n++.0" ) for whichever n your
Re: (Score:2)
So you have documentation for developers (API), community (code contributes), and designers (themes), but the problem area is for users.
IE. you are providing docs for the very smallest percentage of users, and leaving the vast majority of users without documentation.
That seems to be fairly common, but it's completely backwards. Similar to optimizing administration processes while end user processes get ignored because they get paid less or are simply not as well connected.
Come up with some way to document w
Re: (Score:2)
Wow. So your excuse is that you're only dropping this massive rewrite on the audience least able or inclined to absorb it. Way to go.
Re: (Score:2)
If your process was at all stable and reliable, you'd have written the UI design documentation before you coded the UI.
Letting a bunch of programmers loose without a plan is a recipie for inconsistency, unpredictability, and ultimately, disaster for the user.
As others have mentioned, changing the UI so dramatically that you need to keep rewriting the documentation means that the users have to retrain. You can expect them to abandon your project in droves because of the churn.
See Gnome for a lovely e
Re: (Score:2)
I have to agree. If an initial product is good, subsequent versions either extend the product, without invalidating the original documentation, or they introduce unwarranted complexity for little or no gain.
I know the 'improvements' are often (though not always) done in good faith, but superfluous complexity, breaking compatibility, or forcing workers to re-learn the tool they use every day are practically never worthwhile trade-offs.
UX (Score:4, Interesting)
Re: (Score:2)
Agreed. invest in ux.
and when the UX fails? (Score:2)
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
Re: (Score:2)
And many UX projects are a steaming pile of turd that turn users back to ... documentation. Remember the introduction of the ribbon bar? I Office help more the year that was introduced than I did in the preceding 10 years.
The only thing truly absurd in all this is that there are people who think it's an either or game. If you have a great UX your documentation requirements are well reduced, not to mention you can include the documentation the UI itself (pop-up hints when hovering over a checkbox anyone?)
My
Not all documentation is giant documents (Score:5, Insightful)
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.
Re: (Score:3)
Absolutely. There are many advantages to this approach:
* Users can get info they need more quickly as they are already in the correct context to get help on that feature, and don't have to search a document.
* Users are more likely to use integrated help than a huge user manual, saving you support time.
* It is easier to enforce a policy of updating documentation when you update code.
The only thing your separate documentation needs to cover are high-level concepts of the application, and common HOWTOs. If you
Open Source It (Score:4, Funny)
And just make a wiki and the community will do all your work for you.
When every feature undocumented (Score:5, Insightful)
Plus, there is no such thing as intuitive GUI, the best you could possibly do is to have shallow learning curve.
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.
Re: (Score:2)
That's interesting because I see people on a daily basis fumbling with the debit/credit machines at checkouts.
If you stopped standing near the line trying to shoulder surf their PINs you wouldn't see so many.
Even with basic things like swiping their cards.
That's poor design of the hardware, not the software. When you have to figure out where the magstripe is on the card and then where the reader is so you get the right orientation, you're bound to get it wrong. The ATMs I use that have a simple slot to push the card into, I never get wrong. Card comes out of wallet with me holding the end that goes into the machine last. Very simple.
But there are, indeed, int
Re: (Score:2)
If you stopped standing near the line trying to shoulder surf their PINs you wouldn't see so many.
Hurr hurr.
That's poor design of the hardware, not the software. When you have to figure out where the magstripe is on the card and then where the reader is so you get the right orientation, you're bound to get it wrong.
I was referring to both hardware and software in my comment. I've seen on numerous occasions a checkers having to help the person not only to swipe but which options to push in order to finish all the payment steps. And, yes, it is poor design. That was my entire point. The person I responded to said these were "intuitive" yet I've seen numerous people (not even just elderly people) struggle to use them.
The ATMs I use that have a simple slot to push the card into, I never get wrong. Card comes out of wallet with me holding the end that goes into the machine last. Very simple.
That's great for you. Plenty of people still have problems with them.
Re: (Score:2)
An example of one of the most egregious GUI offenders is ... Windows Media Center. If you want to scroll left or right on something (like the program guide so you can see what is on later today) you have to roll over JUST the right spot on the screen and a magical left or right arrow (less than or greater than characters) will appear. Same with up and down. And if you are looking through the list of recorded programs, if you dare keep the cursor over one program too long the entire list will shift to the left so that item is the leftmost. Even if it started as the rightmost. That means you can put your cursor over a program in anticipation of viewing it, pause to read the description to make sure it is the right one, and just before you click on it it will run away and you'll be clicking on the wrong thing.
Using MCE with a remote control is perhaps one of the best user interfaces out there.
Mouse control seems to be an afterthought.
Re: (Score:2)
Re: (Score:2)
Plus, there is no such thing as intuitive GUI
I dunno, I'd say it's fair to call the user interface at most ATMs and credit-card machines intuitive. Granted, some of those user interfaces aren't graphical, but some are.
To put it another way, the learning curve on these things is so shallow that if there's a difference between its shallow learning curve and what you would call an "intuitive GUI" I'm not seeing it.
Everything you think as being "intuitive" is simply you being used to other software behaving in a similar way, or you expecting some icon to match the behavior / usage of a real-world item it kind of looks like. It's training, whether you realize it or not.
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.
Re: (Score:2)
If this is true, where does the widespread notion that nobody reads the documentation come from? Do customers demand documentation for the sake of having it? Or maybe I'm not the only one who reads documentation after all. (Well, I do read it more often than not :-))
Re: (Score:2)
If this is true, where does the widespread notion that nobody reads the documentation come from?
Web comics, stereotypes, and bad jokes.
I only wish I was kidding.
No doc (Score:5, Insightful)
Re: (Score:2)
Re: (Score:2)
Exactly. Even as intuitive "interface" as bathroom signs require explanation at least one time, and even as widespread as bathroom signs, they still do not have uniform notation.
I know, right? I have done a lot of work on bathroom signs, but the jerks keep painting over them..
Re: (Score:2)
Re: (Score:2)
Exactly. Even as intuitive "interface" as bathroom signs require explanation at least one time, and even as widespread as bathroom signs, they still do not have uniform notation.
I know, right? I have done a lot of work on bathroom signs, but the jerks keep painting over them..
Well, if you'd stop putting them on the door to the kitchen...
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.
Target market? (Score:2)
If your target market is not computer literate, than you either need to offer classes in how to use it, or a good manual.
Web 2.0 (Score:2, Funny)
Re: (Score:2)
We're well-past Web 2.0. We're in Apps.0 now.
Snapchat is the king of this shit. They release a video of new features and push it out to all users. There is no description of how to use the features, or when they will be added, etc. You basically have to try touching, swiping, pinching, groping, and otherwise molesting every element of the application in order to find the features.
The same goes with Google. They insist on hiding shit behind swipes. If you see something you now have to try touching it,
Functional spec (Score:5, Insightful)
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? (Score:4, Insightful)
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.
Re: (Score:2)
I realize you are not commercial, and that 2 - 3 week release cycles may not be realistic, but you should release no less frequently than once every 3 months.
Also, if there are so many independent pieces, why do they all need to be released at the same time? This sounds like more of a project management issue than a documentation issue.
Re: (Score:2)
It seems to me that a major problem here is only releasing once a year.
Odoo is commercial, and Open Source.
As an Odoo user and developer I would be happy with a 'release' every two years or more. I can pull bug fixes from the VCS to keep my current system running.
The 'releases' are for big changes and spiffy new features which require a data 'migration' and code 'porting'. Neither I nor my clients want to be doing that every three months. It is an ERP system not some simple desktop app.
Speaking generally (Score:2)
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 goi
plain and simple (Score:2)
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.
Re: (Score:2)
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.
I would even go so far as to define "complex" in the user's context as meaning "requires documentation to use". Users don't care how convoluted your code is, it's complex to them if they need a manual.
I'm concerned about your description of the problem, though. One thousand pages of documentation for four different target audiences and 250 programs. That's one page per program per type of user, on average.
Re: (Score:2)
You are correct 1000 pages of documentation for 250 applications is not very much... either they are very tiny apps or the documentation is very limited.
Don't most companies that develop large amounts of software usually employ documenters that are separate from the developers?
My code is so epic! (Score:2)
Sorry, did you want a serious comment? Oh, you want the Serious Comments Division down the hall...
Dear Slashdot... (Score:2)
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.
Let third parties do it... (Score:2)
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.
Documentation can be opportunity for code review (Score:2)
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.
User docs, or developer/maintainer docs? (Score:2)
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 shou
Re: (Score:2)
Ack. No.
I like OS X / iOS but I get supremely pissed off at Apple's tendency to 'hide' things so the UI looks 'uncluttered'. Yes, you can run an Internet search on the function, but the thesis here is that you write your own documentation, not have Google do it for you.
Re: (Score:2)
How often do you need to do that? As an "end user" when things work correctly, I'd assert it's infrequently.
But when trying to debug a problem, I agree this is frustrating, and the worst of all is "You are unable to log in at this time. A system error has occurred." and even if you know how to bring up the Console (/Applications/Utilities/Console.app) to look at the error logs, they're not particularly helpful.
So I'll put some words into your mouth and say, "It's important to have documentation available
Bad documentation is very, very expensive (Score:2)
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.
Some questions are their own answers (Score:2)
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).
UX? Meh. I have enough experiences in life (Score:5, Insightful)
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?
Re: (Score:2)
Because "Are you interfaced? Have you ever been interfaced?" doesn't sound nearly as sexy.
Ask your customers (Score:2)
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 c
What? (Score:2)
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?
Games. (Score:3)
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).
UX can only go so far (Score:3)
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.
You are doing it wrong, obviously (Score:3)
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
I've used the software (Score:3)
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 least start documentation wiki (Score:3)
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.
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: (Score:3)
See the IBM User Interface Styleguides for where the notion of "F1" as a help key came from.
Microsoft followed CUA; they did not create it.
How about: (Score:2)
Both?
no (Score:3)
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.
UX FTW (Score:2)
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
Re: (Score:2)
"Working software [is valued] over comprehensive documentation"
You then go on to state that this means UX takes priority.
UX does not take priority, the ability of the software to perform its function takes priority. Pretty software that is easy to use but doesn't do what it's supposed to is useless software.
Re: (Score:2)
I'm not confused. I just assumed that people could make a small mental leap: Working software = (functionality + quality + ease of use) whereas comprehensive documentation = waste in order to accommodate for lake of ease of use or poor quality. I hoped that the functionality and quality part of working software would generally be understood without me needing to be pedantic.
Re: (Score:2)
There is no such thing as being pedantic because assumption is the root of all fuck ups.
NEVER assume anything
Consolidate your processes (Score:2)
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
put the documentation in with the code (Score:2)
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 a
User Experience can go a long way (Score:3)
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.
Simplicity (Score:2)
"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
Training videos? (Score:2)
What is easier to fix afterward (Score:2)
Re: (Score:3)
If you need extensive documentation... you had failed.
At Kandy Krush perhaps.
At a real program, not so much.