posted by
janrinok
on Saturday October 11 2014, @05:20PM
from the try-mastering-rsync-without-one dept.
from the try-mastering-rsync-without-one dept.
In my experience it seems like most developers don't like writing the software manuals. Well, Jeff Atwood agrees and thus feels that you shouldn't bother. He likens it to a video game manual... does anyone actually read the manual or do they just start playing? And most games have good "intro" levels. So does your software have an "intro" level that introduces the users to the concepts and tasks without requiring a manual or even online help?
microtodd says, "Actually I used to read the manuals for my games all the time. Baldur's Gate in particular had a great manual."
This discussion has been archived.
No new comments can be posted.
Why Bother Writing the Manual for Your Software App? No One is Going to Read It.
|
Log In/Create an Account
| Top
| 57 comments
| Search Discussion
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @05:33PM
For games and light consumer apps, this might be a reasonable approach to take. But designing an app to be "discoverable" is an even greater skill than writing good documentation. So I expect to see a lot of lazy devs delude themselves into thinking their app is good enough to not need docs.
But even worse, is the state of documentation in the linux arena. Back when I used to code up hill in both directions documentation on unix systeems was bad. Obtuse and it expected you to be an expert. But now it is 10x worse. At least it used to be comprehensive. Now, half the time the only technical details are to be found in semi-random posts on mailing-lists or in forums. It is like pulling teeth to get in-depth details about complex software in the linux world.
(Score: 2) by Lagg on Saturday October 11 2014, @05:41PM
Well, the dept line and the submitter commentary. If you're not an idiot you'll read the manual. No one should have to add extra code needlessly because you want to be lazy. The situation is different in video games because for one thing they're usually tooltips or dialog mixed in with an actual level that you can disable the tutorial for and for another thing video games are entertainment. Tools are tools, trying to implement some kind of silly tutorial stage really just annoys people who just want to jump into it and learn by reference. Manuals proper are also easier to refer to and time spent on an intro stage is time lost for proper manual writing. I also don't think people who like writing manuals are going to be any more willing to write a wall of text or extra code for a tutorial stage, especially since it's undoubtedly harder than just writing a man page.
and yes I do read the manual. I'll just skip over it if it's crappy and gives no good lore or things of that nature but otherwise I definitely read them when they're available. Back when games had a disk space limitation the manual was where most of the good story was in fact. It's a tradition that continues today because oftentimes a short story does more than a cutscene and dialog does. Especially by games that are a homage to said older games like Grimrock which had a short introduction and even a map of the realm.
I knew there was a reason I stopped reading codinghorror. Besides the annoyingly windows-centric articles anyway. At least TDWTF's windows-centric self is that way because most stupid shit is on Windows.
http://lagg.me [lagg.me] 🗿
(Score: 3, Informative) by Thexalon on Saturday October 11 2014, @06:00PM
It's worth noting that for old-school adventure games, reading the manual was often a vital step to being able to successfully complete the game.
The only thing that stops a bad guy with a compiler is a good guy with a compiler.
(Score: 2) by Lagg on Saturday October 11 2014, @07:44PM
That too. A much, much less annoying predecessor to DRM.
http://lagg.me [lagg.me] 🗿
(Score: 2) by Geotti on Sunday October 12 2014, @05:47PM
Oh yeah!
Good ol'
What latitude runs through the center of Skara Brae?
and
Dial-a-Pirate [classicgaming.cc] (one of the coolest feelies, IMHO).
(Score: 2) by VLM on Sunday October 12 2014, @11:20AM
Realistic flight sims are also like that. Especially the combat flight sims.
(Score: 2) by JNCF on Sunday October 12 2014, @08:02PM
Yup, this was early DRM technology. Some games even made you access information in the manual every time you turned them on, like asking for the name of a random monster.
(Score: 2) by Thexalon on Monday October 13 2014, @04:12PM
I was thinking more of King's Quest, where there were puzzles embedded in the game that were easy if you RTFM, and near-impossible if you didn't.
The only thing that stops a bad guy with a compiler is a good guy with a compiler.
(Score: 2) by frojack on Saturday October 11 2014, @05:47PM
Especially if end users, interact with your software via any sort of interface beyond a few variables in a config file, you either have to write the "manual" or watch your software die.
If you are very very good at writing user interfaces, you can actually get away with a minimalist manual. But everything has to be utterly intuitive, and well organized for the user. And programmers aren't the best folks for doing that job.
However the MANUAL these days is best kept on the web as simple web pages, such that you can mine your web logs for page hit stats. The logs tell you a great deal about what is confusing or poorly explained in the software's user interface.
I don't think it pays to write the documentation in book form. Build good help hooks into each part of the system to specific pages, wrap the whole thing with index/TOC, pages and throw it out there for the search engine spiders to find. If you plan your development this way it just gets easier. Don't forget to include a provision for multiple language versions.
No, you are mistaken. I've always had this sig.
(Score: 2) by paulej72 on Saturday October 11 2014, @07:13PM
You mean I need to add writing a Slash Manual to my todo list :(
Team Leader for SN Development
(Score: 2) by BasilBrush on Saturday October 11 2014, @09:07PM
a few variables in a config file
How quaint. I remember having to configure software like that back in the 1990s.
Hurrah! Quoting works now!
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @09:51PM
Yeah, its so easy these days with the OS that uses the multi-megabyte binary blob to store this stuff.
Finding the item that you want to tweak in that giant proprietary-format file is obviously much easier than using task-specific text files.
Having only 1 tool that will do the editing job is also a big improvement.
Needing to have the OS (and the GUI that is welded to it) both up and running to use that specialized tool is the icing on the cake.
-- gewg_
(Score: 0) by Anonymous Coward on Sunday October 12 2014, @03:40AM
Actually, you're right!
It's so much easier to go into the config menu, video output, 1920x1080 than it is to open a command prompt, find the correct config location, change into it, fire up an editor, scroll down 152 lines and then change the text from 720x480 to 192x1080.
Oops, type? I'll have to go back into it and find it, then make the change again.
A few clicks vs a whole lot of typing and knowing how to use the command line.
(Score: 1) by sea on Sunday October 12 2014, @05:05AM
The config menu in the application? So, what if there's a configuration setting that prevents the application from running at all? How do you plan to go into the 'config menu' then? This is a very common scenario. I can't tell you how many times I've had to boot a live distro just to mount the filesystem and tweak config files to get the system back up and running.
How do you take, say, my configuration (which I've conveniently saved on my web page in text format for you) and load it, patch it by appending your own custom stuff, and then load it into your program by clicking around in a 'config menu'? This is also a very common scenario. I've done it countless times. Look up someone's example configuration file online, download it, copy-and-paste the relevant sections into my own config file, BAM, done.
(Score: 0) by Anonymous Coward on Sunday October 12 2014, @06:58AM
Sounds like poorly written software if it can't figure out when its configuration is broken or give you some options for bypassing broken settings. It's still nice to be able to edit your configs by hand but you should never have to.
(Score: 2) by black6host on Sunday October 12 2014, @12:12AM
At one point in my career I was responsible for running a dev team that was writing a group of apps originally written in Clipper. We were moving it to Delphi and taking advantages of all the new things that Windows gave us, such as not being limited to 80x25 text screens.
This suite of applications was used by the client rep department and was by far the largest single suite of all programs we had in house. (Everything was done in house except MS Office and other standard apps, which weren't many) This large application was quite complex as there were so many business rules. It was an insurance type product we were selling and the rules varied from state to state and the application had to handle all scenarios. We had high employee turnover in that department and training was a huge cost. I wanted to write the application so that it would train new employees, keep them from making mistakes and allow them, if a mistake was made, to know why and easily correct it. So I designed it that way. All a CS rep had to do was input data from a form. If they made a mistake, or the form was wrong, when it came time to submit the form and commit it to the database it self checked itself. (Couldn't do it sooner as all fields were interdependent on previous entries.) All fields in error were marked red, a window at the bottom of the screen gave the user a list of what, and why, things were incorrect and they could just click on an item in that list to go fix it. Perhaps they entered the wrong state, or wrong plan number for that state. In any event once they figured out their mistake, which didn't take long, they were back up and running.
Prior to the rewrite the old program had the business rules in it but never informed the CS of what those rules were. Not very handy for the operator.
The gist of it is that our application guided the end user, kept our databases clean and people were able to process twice as much as before. And no need for a manual as the program itself took care of educating the user.
Of course there were other checks and balances elsewhere but overall the change in data quality coming from the new application compared to the old was huge. Training costs dropped as did turnover as people were making fewer mistakes. All of this fit in perfectly for us as no one person could remember all the business rules. But the computer could.... So we let it do the heavy lifting while making it a piece of cake for the folks who were using it.
(Score: 1) by Pino P on Sunday October 12 2014, @02:26AM
However the MANUAL these days is best kept on the web as simple web pages
That's fine if you give users an option to make the whole manual available offline. Otherwise, having an online-only manual for a desktop or tablet application isn't very convenient for someone who wants to use the software while riding transit or otherwise not connected to the Internet.
(Score: 0) by Anonymous Coward on Sunday October 12 2014, @06:16AM
if you give users an option to make the whole manual available offline
More specifically, if you do NOT use some proprietary nonsense and just make your stuff plain old HTML pages, everything works out great.
Earlier in this thread, wget was already mentioned. [soylentnews.org]
Just download the online manual so that you have it locally.
If you tell it to, wget will even make the links within the pages you download relative [google.com] rather than absolute (or whatever the proper terms are).
-- gewg_
(Score: 1) by ksarka on Saturday October 11 2014, @05:48PM
Well it depends on the level of software that is being used. If it's some application that is based on few mouse clicks and that's it - I agree, fuck the documentation for that. A software package that solves some real and complex problem - even after several years of using it I find myself regularly opening the manual to consult on one issue or another. Thank goodness the devs of those spent their valuable time to make my life easier.
As for the comment on video game manuals - I used to read them when they still had some relevant information, such as stats, descriptions of monsters, lands, lore, items etc. In the last 10 years, I noticed that either they moved everything to wiki's or the manuals coming with the games are complete bullshit with no relevant information.
(Score: 2) by frojack on Saturday October 11 2014, @06:19PM
I find it sort of sad that the topic turns to video games when ever software development is mentioned here on SN.
FFS, people you are sitting at a computer posting this stuff!! I don't care what kind of computer it is, the HELP is offered for every software program you use daily. The HELP is the Manual. The manual has morphed into help. And Marshall McLuhan saw it coming.
No, you are mistaken. I've always had this sig.
(Score: 0) by Anonymous Coward on Sunday October 12 2014, @03:48AM
Why do you find this sad? Gaming is what a significant portion of human and CPU time is used for.
Ah yes, the old "Just hit the help button!"
Nothing quite like having to read the help, background it, go into the software, open up the window and then, because you've forgotten what the help file said to do by now, click back to the help - oh it's modal so I can't put the dialog behind the help in order to re-read it.
Close the dialog, go back to the help, re-read it, find I have to remember some icon to look for, go to the software, re-open the dialog, find the icon.. wait, is it this icon, or that one? Fucking hell, I can't remember.
Close dialog, go back to the help, take a fucking photo of it on my phone, back to the software, re-open the dialog, find the icon, compare it to the photo, then make the changes.
Approximately 250% of the population have great difficulty recalling what they see. Once egos and anosognosia are taken into account (I'm thinking of my ex- here) we start to find that a significant portion of the population have great difficulty recalling precisely what they saw just a few moments ago. Some people are like this because of natural retardation, some because of external influences (physical assault/abuse, or drugs), and some because of stroke.
If you can hold a printed manual in your hand, you can compare it with the screen and make notes if necessary.
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @06:13PM
I'm too lazy to write a good manual, so I'm going to assume everyone else is lazy too and doesn't read them to justify it to myself.
So very transparent, this is even worse than using a wiki as a manual.
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @10:07PM
While I agree with your 1st point, your 2nd point seems to indicate you haven't ever visited the Arch Linux wiki.
With bootable removable media available to get you up and online even when your OS is completely titsup, a wiki can be an excellent resource.
...and there's nothing keeping you from doing a wget and putting the whole wiki on a thumbdrive in case you are going to be somewhere they have electrical outlets but not internet connectivity.
-- gewg_
(Score: 3, Insightful) by maxwell demon on Saturday October 11 2014, @06:20PM
Unfortunately nowadays software rarely comes with a manual worth reading.
The Tao of math: The numbers you can count are not the real numbers.
(Score: 2) by Immerman on Saturday October 11 2014, @09:15PM
If you're referring to a physical paper document, absolutely. On the other hand the help files have taken over the same basic role - one to which hypertext is particularly well suited. Some software is actually very well documented in that format, and I for one always appreciate it. Especially if there's a concise overview of features to complement the discoverability of the UI.
(Score: 0) by Anonymous Coward on Sunday October 12 2014, @03:52AM
I prefer a paper manual sometimes, so I can refer to it while using the software. Look up, look down and read, look back up. Digital manuals don't always help with this.
One thing I absolutely adore about digital manuals is the manual that has a small animation showing you where to click, or the one that moves the mouse to the position so you can click on it. Stops me struggling, looking all about the place, to find that one button I've forgotten the location of.
I can't recall which particular manuals do this, but I'm sure I've come across some.
(Score: 2) by Immerman on Sunday October 12 2014, @04:22AM
Two words: Multiple monitors. Program on the main screen, help file on a secondary one. Look back and forth as you like.
I'll grant you paper has its place though, there are most definitely a few manuals, textbooks, etc I keep on hand.
(Score: 5, Funny) by kaszz on Saturday October 11 2014, @06:40PM
* You may only keep a copy of the material herein inside you brain for the duration of ownership of this product or else our lawyers will send you to Gitmo along with your cat.
* Read and understand all letters in this manual. Our representative may cross examine you and failure will render warranty void.
* Use a grounded outlet or you must order a letter of indulgence from your electrician for your mortal earthing sins.
* Bathing together with this product may have negative consequences for your life expectancy. Our funeral warranty service will not cover this.
* Placing the product in front of the entrance door is not recommended. Neither is hanging it by a very thin wire from the ceiling recommended.
* If the product doesn't work as you expect. Using a sledgehammer will not solve the problem and is not covered by warrranty. Microwaving isn't recommended either.
* Letting you baby try to repair this equipment is not recommended.
* This device is only compatible with evil people from Seattle, or as a secondary option in some cases with white plastic people from Cupertino.
* Using non-metered 8 kV directly from your power company may overheat the device.
* Comes with pre-installed WiFi backdoor in case some of our state friends needs your device.
* You may contact us at anytime between 4:24 - 4:25 am on Thursdays on even weeks in leap years. After you completed our support contract and personally delivered it to our branch office in Madagascar at said time.
* To ensure energy usage compliance never plug the power cord into an outlet otherwise warranty is void.
* Any bad smell from device usage may come from nerve gas. This is perfectly normal. Most users will survives this.
* Placing the device in your kitchen oven is not recommended.
* Usage of electrical power may be benefitial to device operation.
* Turning the device upside down may impede reading of labels.
* Dipping the device in epoxy may impede operating user controls.
* Banging your head on the device may hurt. It's not covered by warranty.
(Score: 2, Funny) by crAckZ on Sunday October 12 2014, @12:30AM
and yet someone will die trying to lick it
(Score: 3, Insightful) by Anonymous Coward on Saturday October 11 2014, @06:50PM
Software makers write bad manuals, and no one reads them. so they write lesser and crappier manuals.
It used to be a job that needed to be done, and it was difficult. It still is. Now they hire an intern to write some trivial things about the software, and he does, then no one reads it. Then management sees that no one is reading it, so they put less effort into it next time, and the cycle repeats until we get to a point (today) where people say no-one should write manuals. Its sad.
(Score: 2) by Magic Oddball on Sunday October 12 2014, @12:30AM
There was also a period of time (80s/early 90s) where software companies hired writers to go through the software and write manuals for it. Even if the person was also technically inclined, they usually had a better idea of what regular users might find difficult or confusing, and were skilled in explaining or describing things.
(Score: 2, Informative) by art guerrilla on Sunday October 12 2014, @10:57AM
1. i guess one of the signs of my particular brand of nerdinesss, is that i *do* read the fucking manuals, and they *are* generally crap, in all kinds of ways...
2. ONE major way manuals are crap, is 'explaining' commands with self-evident superficial crap that is useless... this is nearly verbatim: "DRAW; the DRAW command draws lines..." bearing in mind that this DRAW command has a dozen options, various contexts, and variations they don't bother to MENTION much less explain...
steam starts coming out my ears when i run across crap like that...
3. screenshots that are so pixelated you can barely tell one icon from another WHICH IS THE WHOLE POINT OF THE GRAPHIC...
4. for that matter, stupid fucking icons that you have NO IDEA what they are trying to 'represent', and there is no tooltip rollover to give you a clue... you know what, i can *still* read, in *spite* of being a computer user, why don't you try putting these things we call 'words' into an arrangement we call 'menus' then i can READ what the damn command is supposed to be and probably figure it out that way... i don't know how many nerd-years i have wasted trying to figure out what some icon-from-mars was supposed to do that i am not familiar with 'cause i don't use those functions but once in a blue moon...
5. the number of times i have been pleasantly surprised by decent manuals is 1 millionth the times i have been angered by shit manuals...
6. not to mention, we buy fairly expensive CAD/etc s/w, and they don't even bother to send a dead tree manual any more: i pay 10 thou for a damn blob of bits, and i can't get a damn dollar paper manual out of you useless pukes ? ? ? i *want* to read the manual, (even if its no good) but -duh- i'm not in front of a monitor 24/7, but i can carry around a damn book and look at it while i'm on the toilet, read it with my lunch, etc... can also make notes, etc in the margins, that is not easily done with online manuals...
*with* a coil binder that lies flat, would be nice, thank you very much...
(Score: 0) by Anonymous Coward on Tuesday October 14 2014, @01:49PM
Dead-tree paper instruction manuals are...dead!
The bean counters determined they were too expensive to produce and ship with software.
So now all 'serious' retail software that comes in a box is essentially 'paperless' except for the software distribution CD/DVD and a 'quick start install card' (if that).
If the software vendors want to avoid enraging people like you with a dearth of instructions, the could integrate the manual WITH the software properly or design the user interface with such care and attention to detail that a paper manual describing how to use it would be TOTALLY redundant.
(Score: 4, Informative) by Appalbarry on Saturday October 11 2014, @06:54PM
Having grown up with Microsoft, spent a few years trying to be Apple user, and finally settling into Linux, I feel I can offer some perspective.
The question shouldn't be "Should you write a manual?"
Instead you should be asking "How can end users find answer to problems they have?"
In the past a printed manual made a lot of sense - no serious WordPerfect user would ever leave home without their big, fat copy of Karen Acerson's bible.
That was pre-Internet though, and things have changed significantly. Today a manual is really not a sensible route in most cases. A well-designed web-site, or even active user forums, will usually yield a good answer faster and easier than a big printed book.
Hell, I'll argue that in this age Google is, by default, the manual for most software products. A reasonably well constructed query will usually turn up an answer in a few minutes.
Thinking about it, the only time that I start at a manufacturer or publisher's web site is when I need something like drivers - things that can only be got there. In recent years I haven't found that the "official" site will be likely to have what I need, or even to acknowledge the problem exists.
I generally assume that a user forum is where I'll find other people with my problem, and usually will also find a fix.
Notes:
1) I'm old enough to remember the Man Page nazis of yore. As a beginner Linux user, long before things like Ubuntu and Mint, I found Man pages to be stunningly useless and frustrating. The main problem being that every Man page can only be understood of you already understand three other Man pages that it refers to, each of which also can only be understood if....
2) Programmers generally are the last people who should write manuals or instructions. It is simply not possible for them to see the software as an end user will see it.
3) Nothing makes me have more confidence in a program or app than an actual e-mail address to someone who can answer a question.
4) If your manual runs beyond 200 pages, I consider you to owe me a real paper copy, not a PDF. And if there a choice between a downloadable PDF and a whole web site full of manual pages, I'll choose the PDF.
5) The less said about most wikis, the better.
(Score: 2) by maxwell demon on Saturday October 11 2014, @07:51PM
A manual is a text type, not a medium type. A manual doesn't stop being a manual if you put it on the web as HTML files, instead of printing it as book (BTW, I find that HTML manuals are usually lacking features which dedicated help systems used to have, like good indices and a good search function).
The Tao of math: The numbers you can count are not the real numbers.
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @08:45PM
I think the difference is that back in the '80s, there weren't quite as many demands on people's time as there is today - no Internet or mobile phones, and "globalization" of large corporations and their workforces had just been innovated by Jack Welch of GE. So people had time to study and master one or two large desktop software products that they depended on.
That's not the situation today. In the last 5-8 years I've bought and thrown out (or given to Goodwill) three different books on Excel and MS Office, which I hoped to read but never got past the first chapter. I just got a sinking feeling - there's just not enough time for this. Now, maybe if I was a lawyer (using MS Word) or an accountant or corporate analyst (using Excel) then I'd have more motivation.
(Score: 2) by gman003 on Saturday October 11 2014, @08:46PM
As a larval user, I once ran the command "ls /bin | xargs man". The results were enlightening, though I'd hardly call that a "user-friendly" introduction. But it did power me through the problem of dependencies.
PS: The man page for sudoers is still, by far, the worst man page I've ever seen, and that's including the numerous ones that simply say "use GNU info instead". Yes, having a formal grammar for the file is nice. You do not need to teach me BNNF to teach me how to read those specs, you need to give trivial examples of how to grant certain users access to certain things.
(Score: 2) by microtodd on Sunday October 12 2014, @12:29AM
Interesting point. I don't think I've ever really used any software manual in a useful way. But there are many O'Reilly books or tutorial websites I use all the time for particular apps. The app I've used lately that I needed help with is Jira/Mercurial. The online help is not very useful but I have slogged through it to find out things that I need to do.
(Score: 1) by calzone on Saturday October 11 2014, @07:00PM
RTFM!
Time to leave Soylent News [soylentnews.org]
(Score: 0) by Anonymous Coward on Sunday October 12 2014, @03:57AM
Did the manual install?
Is it under man or info?
Or is it built into the software?
Does it reflect this particular version?
Is the concept you're looking for actually in the manual?
Are they using the appropriate terminology?
Do they tell you what you need to know, or is it convoluted and difficult to understand?
Is it written by the developer just as a reminder to himself?
Is it wall-of-text?
RTFM makes too many assumptions.
(Score: 1) by number6 on Saturday October 11 2014, @07:41PM
A fixed-in-stone 'manual' can never address every possible usage pattern, BUT.... if the interface was totally customizable, then the user could slowly develop his own 'manual' system.
'Manual ' should not have to be just one compiled document with an entry point under 'Help at the toolbar. If the user was given the freedom to fully customize the toolbar and menu items, then he could create his own entry point(s) under the 'Help' menu.
If I stay with a particular software for a long enough time, I usually end up creating a personal help system for myself; a folder where I dump and sort all types of useful documents, snippets and clippings. If the software allowed me to totally customize its toolbars, then I could add an entry point named 'My Help' under the 'Help' menu.
If I select 'My Help', a custom launcher pops open. This launcher is like a cross between the 'Firefox' bookmarks manager and the (Windows) program 'PStart':- it is searchable - I can drag-drop folders files and URL's into it - items have properties pages - item icons and display text are changeable - selected items launch with specified commands and scripts.
With such a customizable software, my need for a perfect built-in documentation system from the software developer is not important.
Being the type of guy that I am, my heart always wants to give userland the maximum control and freedom possible:
- Create software which does not hold the user back from doing anything he wants with it.
- Open source the code, and include profuse notes, comments and debugging tips so future and ancient users can all benefit and modify it.
- Have zero interest in personal fame or glory or selling out to big business; if there is to be a business model it would be like Soylentnews.
I feel that Jeff Atwood is highlighting another manifestation of the current explosive debate about the 'dumbing down' of software interfaces and the lack of community spirit by so many developers today; a sheer unwilligness to think about userland in a truly loving way.
(Score: 2) by BasilBrush on Saturday October 11 2014, @09:13PM
Customizable UIs are the enemy of documentation, tutorials and help. When people need to go looking for help, they need to see screenshots or videos that look somewhat similar to what's on their screen.
Hurrah! Quoting works now!
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @10:08PM
^ Bullshit. You didn't negate anything he said. You don't *know* what people need. You are just another bigmouth dev who thinks he knows better. At the end of the day what the guy described is open to all possibilities ....including yours!
I've had enough of devs locking down UI's and giving terse reasoning such as yours. Why don't you do me a favour and list down all software projects you develop so I can add them to my blacklist of 'boring computing shit not worth one second of my time'.
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @10:35PM
Imagine trying to do helpdesk support over the phone with someone with a have-it-your-way UI.
A customizable UI needs a Toggle back to default config button.
End of problem.
-- gewg_
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @11:06PM
If the app was designed by a super-intelligent programmer who thinks just like the OP, the customizable UI would have a 'back to default' config button AND would auto-save the customized layout as a theme file in a subfolder named 'Themes'.
For an example of this, see the (Windows) software 'foobar2000'. It is super-extendible using plugins. You can basically do anything you want with its layout. There is a third-party plugin made for it named AutoSave & AutoBackup ('foo_jesus.dll'). This plugin will save the current configuration and theme at specified intervals so you never have to worry about things like this again---just open its Preferences page and re-import your theme and you are back to where you left off.
foobar2000 is a perfect example of how all software should be designed. Any dev who cannot fathom creating software which empowers users like this should fuck off and do something else with his life and stop trying to advise the rest of userland about shit he knows fuck-all about.
(Score: 1) by archfeld on Saturday October 11 2014, @07:41PM
Call me strange, many others have and continue to do so, but I have a filing cabinet filled with old gaming manuals, back to the gold box D&D games that won't run on anything anymore. I also collect RPG rule books all the way back to the original red and blue D&D game manuals including the crayons, Boothill, Gamma World, Tunnels & Trolls, and many others.
For the NSA : Explosives, guns, assassination, conspiracy, primers, detonators, initiators, main charge, nuclear charge
(Score: 2) by Gaaark on Saturday October 11 2014, @07:53PM
I too have kept some old manuals... some of them simply because they look amazing.
I used to just jump into the software and use it, then in my spare time read the manual for tips/ideas to improve my gameplay/usage.
^This especially with games. Who wants to spend an hour+ reading the manual... you start playing and after dying a few times, you read the manual and go 'aha!', and start playing again.
--- Please remind me if I haven't been civil to you: I'm channeling MDC. ---Gaaark 2.0 ---
(Score: 1) by Twike on Monday October 13 2014, @12:09AM
Please type the seventeenth word in the third paragraph on the fifth page of the second section of the manual to continue:
(Score: 1) by Refugee from beyond on Saturday October 11 2014, @07:57PM
Yeah, sure. imagemagick without manual. I can see that *cough*
Instantly better soylentnews: replace background on article and comment titles with #973131.
(Score: 0) by Anonymous Coward on Saturday October 11 2014, @09:50PM
The lack of software manuals has created a market for books. How many 'For Dummies' books were out there for every application under the sun.
The need for instructions are there, and it gets fulfilled by the people who write the books, create tutorials, create videos, etc. There is very little software that is intuitive enough not to need some instruction. More manuals would mean people could try out the software up front, because the education about its use is right there. Lots of good software is probably passed over, as there is no quick access to detailed information.
The old software, like Central Point PC Tools back in the day, came with a full set of books. The 2 sheet manuals, with CD of buried PDF documents, they produce today pale in comparison.
(Score: 1) by Valkor on Saturday October 11 2014, @11:07PM
Starcraft 1 and Sid Meir's Alpha Centauri both had great manuals. SMAC was basically a book at 247 pages, and read like one too for half of it. Full histories and backgrounds of all the major factions, descriptions of universe as a whole. Great stuff. Nobody ever does this any more, so there's becoming little to no incentive towards getting a physical boxed copy of the software.
(Score: 3, Informative) by fadrian on Saturday October 11 2014, @11:34PM
Well, for libraries, it's because your Javadocs (or whatever PoS documentation generator you use) suck. Seriously. I've never seen a good set - they're either incomplete obvious or show no way to actually use your library. You know that people actually need conceptual guidance as opposed to "The input myFoo of type Foo takes a Foo as an input. Well that's just fucking useful, isn't it? And maybe your boss gauges you on the number of docs turned out, but I judge on the actual utility of the docs. And, frankly, yours suck.
That is all.
(Score: 2) by clone141166 on Monday October 13 2014, @03:04AM
* Gets the discombobulation.
*
* @return discombobulation
*/
Discombobulation& getDiscombobulation();
I remember some really terrible software from MatrixOne where almost every function's documentation looked like that. And then they went and hid a whole bunch of functions in static methods of "utility classes". So even if you had an object and were looking at the function documentation for it, half the functionality for the object was hidden away in some other ***Util class as a bunch of static methods. Fun times.
(Score: 2) by halcyon1234 on Sunday October 12 2014, @03:23AM
Yes, you should write your manual. You should go step by step through your software, document each click and button press. Take screenshots of each screen, each changing UI. Draw circles and arrows all over it.
Why? Because it FORCES you to actually use the system as it is, not as you think it is, or remember it being. It removes your developer blinders. You suddenly see every UI mistake. You come across ever bug a user would come across. You get to test processes you coded in Phase I that you broke in Phase III and didn't even know.
You get to PROVE that your software works. In one bit of effort, you do self-training, writing a manual, and do a big chunk of QA.
But then again I forgot-- this is Jeff Attwood. This isn't about what works or what doesn't. This is what he feels is right. And if you do it different, you're Doing It Wrong!!! And if Jeff doesn't personally use it, then it's obviously of no use and no one should use it.
Original Submission [thedailywtf.com]
(Score: 2) by mcgrew on Sunday October 12 2014, @11:49AM
My two biggest complaints about today's hardware and software is lack of good documentation, and lack of any documentation at all. A primitive TS-1000 had a manual half an inch thick, my Android has a little five page booklet, and it would have been a supercomputer in 1980. Android's online "documentation" is worthless. It tells you what the phone will do, but not how to make the phone do it.
The reason "nobody" reads documentation is that "nobody" reads, period. Only something like 3% of Americans have read a book in the last year. Most people will only read when absolutely necessary. We no longer have an illiteracy problem, but we have a terrible aliteracy problem.
As Mark Twain noted, those who don't read have no advantage over those who can't read.
A product, especially a complex product, that has no documentation or shoddy documentation is a shoddy product, period.
Carbon, The only element in the known universe to ever gain sentience
(Score: 2) by darkfeline on Monday October 13 2014, @01:31AM
Games are experiences. Tools are, well, tools.
When I play a game, I enjoy experimenting and discovering cool tricks or idiosyncrasies in the physics engine. When I'm using software to do something, I do not enjoy learning about undocumented behavior that screws up something important.
I have yet to hear someone complain about, say, chainsaws being unintuitive or user-unfriendly. It's a tool, and anyone who picks up a chainsaw expects that they need to know how to operate it first.
Now, that's not to say that every piece of software (particularly "apps") needs a traditional document-style manual. If all your app does is turn on the phone's camera flash, then a simple toggle button and maybe a warning that extended use drains battery power and heats up the phone etc. etc. is enough (intuitive UI controls, akin to self-documenting code), but at the end of the day, your app should be documented, and that documentation should be readily available.
Join the SDF Public Access UNIX System today!
(Score: 0) by Anonymous Coward on Monday October 13 2014, @02:45PM
You've got to really know what you're doing though and the customer has to realize they really have to read the manuals ;).