Want to read Slashdot from your mobile device? Point it at m.slashdot.org and keep reading!


Forgot your password?

Slashdot videos: Now with more Slashdot!

  • View

  • Discuss

  • Share

We've improved Slashdot's video section; now you can view our video interviews, product close-ups and site visits with all the usual Slashdot options to comment, share, etc. No more walled garden! It's a work in progress -- we hope you'll check it out (Learn more about the recent updates).

Software GUI Open Source

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

Posted by timothy
from the ask-your-users dept.
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?"
This discussion has been archived. No new comments can be posted.

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

Comments Filter:
  • Yes. (Score:2, Insightful)

    by Nimey (114278)

    en tee

    • 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)

    by aeschinesthesocratic (1359449) on Thursday August 14, 2014 @02:03PM (#47671929)
    Invest in both.
    • by ShanghaiBill (739463) on Thursday August 14, 2014 @02:42PM (#47672359)

      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.

      • It works for my company!

        (well not really but they keep trying to make everything a priority anyway )

    • 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)

        by mjwx (966435) on Thursday August 14, 2014 @09:02PM (#47674851)

        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.

  • by seebs (15766) on Thursday August 14, 2014 @02:03PM (#47671939) Homepage

    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.

    • by Fabien Pinckaers (3785215) on Thursday August 14, 2014 @02:12PM (#47672033)
      We actually have four documentations: developers, community (how to contribute), designers (how to develop theme), users (accountant, crm, point of sale, ecommerce, ...) The first three are stable enough and we will for sure invest in a great documentation. But the latest, the business apps, will evolve a lot in the coming months as they are plenty of areas to improve. My question relates only to the user documentation. For developers and designers, we more or less freeze the api/interfaces.
      • 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).

      • by seebs (15766) on Thursday August 14, 2014 @02:29PM (#47672217) Homepage

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

        • If by "plenty of areas to improve" they meant the code and interfaces, then I agree with your statement: the end-users need something stable, minimum for 1-2 years. THAT DOESN'T MEAN SEPARATE VERSIONS CAN'T BE MADE! largely relying on the same codebase, it's just that when a large groups signs-up at first they need to be able to learn and keep a solid set of expectations.

          If by "plenty of areas to improve" they simply meant the documentation for business use, however, then it just means they need the docu
      • by BaronM (122102) on Thursday August 14, 2014 @02:31PM (#47672227)

        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)

          by khasim (1285) <brandioch.conner@gmail.com> on Thursday August 14, 2014 @02:49PM (#47672423)

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

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

          Do this.

          And make the error reports unique. No more "an unexpected error has occurred". Even "purple-monkey-dishwasher" is better than that. Make it easy for your users to report real problems to your developers. And that means making each error unique enough that the developers can search the code for it.

          And have someone spend some time sorting through your forums (make sure you have forums) who can move threads and messages around while still maintaining the links to them. So someone with a "purple-monkey-dishwasher" error can see the other posts about that WITHOUT having to dig through unrelated "vitamin-can-hook" errors. Sortable by version. And by date.

          • Make it easy for your users to report real problems to your developers.

            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
        • by i_ate_god (899684)

          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.

        • by mjwx (966435)

          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.

      • by ravyne (858869) on Thursday August 14, 2014 @02:39PM (#47672323)
        Having a well-thought-out, consistent, orthogonal, and to-the-extent-possible obvioius UI can go a long ways toward the user experience, bring relevent information nearer to the user, and even make the documentation easier to write -- but even having achieved that ideal, UI/UX cannot and will not substitute for documentation.

        At the end of the day, your users have a business goal, and you've sold them on the idea that your software package will help them achieve it better and more easily than other solutions. You sell solutions and solution components, but you also sell 'better' and 'more-easily'. Documentation is necessary, no amount of UI will take you from splash screen to solution whilst navigating a large set of outcomes and a series of interdependent choices.

        DO provide UI reference, but scenario-driven documentation is your users' greatest need.
        DO automate common, simple tasks to the extent possible.
        DO make doing the right thing easy, and wrong or dangerous things hard.
        DO bring the most relevant information into the app in abbreviated form (apply the 90/10 rule)
        DO link the UI to relevant documentation.
        DON'T get hung up on covering every possible scenario (again, 90/10 rule)
        DON'T believe that a perfect UI avoids the need for documentation.
        DON'T try to bring all the documentation into the UI.
        DON'T rely on your own intuition about what's common or difficult for users, ask them or collect the data.
        • 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

      • by unrtst (777550)

        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

      • .My question relates only to the user documentation. For developers and designers, we more or less freeze the api/interfaces.

        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.

      • by msobkow (48369)

        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

    • by Livius (318358)

      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)

    by Raven42rac (448205) on Thursday August 14, 2014 @02:05PM (#47671963)
    No one reads documentation.
    • by rssrss (686344)

      Agreed. invest in ux.

    • 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

    • by thegarbz (1787294)

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


  • by penguinoid (724646) <spambait001@yahoo.com> on Thursday August 14, 2014 @02:06PM (#47671971) Homepage Journal

    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.

    • by pavon (30274)

      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

  • by Anonymous Coward on Thursday August 14, 2014 @02:07PM (#47671981)

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

  • by sinij (911942) on Thursday August 14, 2014 @02:07PM (#47671987) Journal
    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.
  • by NotDrWho (3543773) on Thursday August 14, 2014 @02:11PM (#47672025)

    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.

    • by reikae (80981)

      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 :-))

      • 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)

    by Oligonicella (659917) on Thursday August 14, 2014 @02:12PM (#47672037)
    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.
    • by sinij (911942)
      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.
      • 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..

        • by sinij (911942)
          This is because you don't properly encapsulate interfaces and don't adequately document mounting and unmounting process.
        • 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...

  • by fuzzyfuzzyfungus (1223518) on Thursday August 14, 2014 @02:12PM (#47672039) Journal
    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.
  • Look, if your target market is highly computer literate than a manual is not a big deal (assuming the program is well written and intuitive).

    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)

    by Jaime2 (824950)
    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.
    • 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)

    by mspohr (589790) on Thursday August 14, 2014 @02:21PM (#47672133)

    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.

  • by BitZtream (692029) on Thursday August 14, 2014 @02:23PM (#47672149)

    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.

    • It seems to me that a major problem here is only releasing once a year.

      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.

      • by smugfunt (8972)

        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.

  • 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

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

    • by Obfuscant (592200)

      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.

      • 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* my documentation!

    Sorry, did you want a serious comment? Oh, you want the Serious Comments Division down the hall...

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

  • 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 shou

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

      • 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

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

  • 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).

  • by caseih (160668) on Thursday August 14, 2014 @02:38PM (#47672303)

    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?

    • Why can't we go back to calling it what it is: user interface?

      Because "Are you interfaced? Have you ever been interfaced?" doesn't sound nearly as sexy.

  • 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

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

    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?

  • by pla (258480) on Thursday August 14, 2014 @02:49PM (#47672421) Journal
    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).
  • by Dracos (107777) on Thursday August 14, 2014 @02:55PM (#47672479)

    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.

  • by angel'o'sphere (80593) on Thursday August 14, 2014 @03:02PM (#47672543) Homepage Journal

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

  • by Pop69 (700500) <billy@@@benarty...co...uk> on Thursday August 14, 2014 @03:08PM (#47672585) Homepage
    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.
  • by raymorris (2726007) on Thursday August 14, 2014 @03:13PM (#47672619)

    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.

  • by tlambert (566799) on Thursday August 14, 2014 @03:22PM (#47672681)

    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.

    • by msobkow (48369)

      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.

  • Both?

  • by Charliemopps (1157495) on Thursday August 14, 2014 @03:57PM (#47673003)

    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

    • by Pop69 (700500)
      You seem to be a little confused.

      "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.
      • 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.

        • by Pop69 (700500)
          If there's one thing that experience has tough me it's this.

          There is no such thing as being pedantic because assumption is the root of all fuck ups.

          NEVER assume anything
  • 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

  • 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

  • by mysidia (191772) on Thursday August 14, 2014 @07:41PM (#47674415)

    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.

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

  • 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 alternati
  • I would favor user interface: it is easier to add missing doc afterwards than fixing a bad UI.

It's not so hard to lift yourself by your bootstraps once you're off the ground. -- Daniel B. Luten