# Through the Looking Glass with User Guides! **URL:** \ **Category:** Miscellaneous and Personal Stuff I Must Share\ **Created:** [July 7, 2009, 11:02pm UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268 "2009-07-07T23:02:11Z")\ **Posts on this page:** 8\ **Page:** 3
**Author:** ![Morbo](https://sea3.discourse-cdn.com/straightdope/user_avatar/boards.straightdope.com/morbo/32/389_2.png) [@Morbo](https://boards.straightdope.com/u/Morbo)\ **Post date:** [July 9, 2009, 12:37am UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268/41 "2009-07-09T00:37:09Z")
> [@zagloba](#): > > Has “marketecture” actually been spotted in the wild? Wow! I’m afraid [so](http://www.marketecture.biz/). ---
**Author:** ![mhendo](https://sea3.discourse-cdn.com/straightdope/user_avatar/boards.straightdope.com/mhendo/32/3159_2.png) [@mhendo](https://boards.straightdope.com/u/mhendo)\ **Post date:** [July 9, 2009, 2:53am UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268/42 "2009-07-09T02:53:43Z")
> [@Seven](#): > > You know what I find interesting? > > How did **bwaldie** find this thread in under 3 hours of it being posted? Threads quite often end up being indexed by Google that quickly. ---
**Author:** ![dropzone](https://sea3.discourse-cdn.com/straightdope/user_avatar/boards.straightdope.com/dropzone/32/7515_2.png) [@dropzone](https://boards.straightdope.com/u/dropzone)\ **Post date:** [July 9, 2009, 3:10am UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268/43 "2009-07-09T03:10:26Z")
> [@InvisibleWombat](#): > > 1. Tech writing is a discipline of its own. It isn’t the same as writing general nonfiction or novels. So, I’ve demonstrated I can’t write fiction. Any jobs for me in tech writing? 😉 ---
**Author:** ![El\_Zagna](https://avatars.discourse-cdn.com/v4/letter/e/d2c977/32.png) [@El\_Zagna](https://boards.straightdope.com/u/El_Zagna)\ **Post date:** [July 9, 2009, 3:36am UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268/44 "2009-07-09T03:36:19Z")
> [@Morbo](#): > > Software engineers and programmers have nothing whatsoever to do with writing Help Files and User Guides. Hate the UA / Tech Writers. That’s not been my experience. It’s common for the same people who wrote the code to write the documentation. It’s a bad way of doing it, but it’s common. ---
**Author:** ![El\_Zagna](https://avatars.discourse-cdn.com/v4/letter/e/d2c977/32.png) [@El\_Zagna](https://boards.straightdope.com/u/El_Zagna)\ **Post date:** [July 9, 2009, 4:11am UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268/45 "2009-07-09T04:11:20Z")
> [@Floppy\_Joe](#): > > Been using personal computers since there were personal computers. It has been my experience with software manuals, that they will tell you what each function does. They do NOT tell you how each function can be used. Boy, you’re absolutely right about that. The most common mistake in documentation - whether at the product level or at the code level - is saying what it does, not why it exists. Every piece of documentation should start off with, “The purpose of this function (or module or application) is to \_\_\_\_\_\_” or words to that effect. There was a time in my career when I looked at a lot of software coming into the market, and I would study their literature and read the journals and still be left wondering, “OK, but how is that going to help me?” Or in marketing parlance, “What pain does it address.” > [@Floppy\_Joe](#): > > That’s the way it is. Ranting & pitting will not change that. I disagree. When people start returning products to the store saying, “I couldn’t figure out how to get the damn thing to work, so it’s useless to me,” then you’ll start seeing companies put more effort into not just the documentation, but the usability factors in general. ---
**Author:** ![Seven](https://avatars.discourse-cdn.com/v4/letter/s/3d9bf3/32.png) [@Seven](https://boards.straightdope.com/u/Seven)\ **Post date:** [July 9, 2009, 6:53am UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268/46 "2009-07-09T06:53:58Z")
> [@mhendo](#): > > Threads quite often end up being indexed by Google that quickly. Something tells me this isn’t the case here. ---
**Author:** ![Nava](https://avatars.discourse-cdn.com/v4/letter/n/da6949/32.png) [@Nava](https://boards.straightdope.com/u/Nava)\ **Post date:** [July 9, 2009, 11:14am UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268/47 "2009-07-09T11:14:32Z")
99% of them aren’t user manuals: they’re programmer’s documents or marketing brochures, and bad ones at even that. Back when I did Quantum Chemistry, I would have recommended Spartan over any other program in the world simply because its manual was done in terms of “HOW do I accomplish (task)?” Where most manuals would have had, say, “usage of multi-orbital interactions for bferfoaghf algejod” hidden in a list of other equally-clear lines, or would say “you can use Our Magnificent Program to calculate the most-stable energy state of molecules including third-row elements” but not say _how_, Spartan’s index would list “how to include third-row elements.” Tadaaa! That’s how I write my manuals - for some reason, users love my manuals but project managers throw a fit, so I’ve learned to let my Key User have a sneak preview before the PM makes me “rewrite it properly”… mwahaha ---
**Author:** ![Crotalus](https://sea3.discourse-cdn.com/straightdope/user_avatar/boards.straightdope.com/crotalus/32/41_2.png) [@Crotalus](https://boards.straightdope.com/u/Crotalus)\ **Post date:** [July 9, 2009, 4:21pm UTC](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268/48 "2009-07-09T16:21:10Z")
> [@Seven](#): > > Something tells me this isn’t the case here. I think it is. We recently had a thread in Cafe Society about guitarist James Burton, and the person who runs Burton’s web site showed up pretty quickly. She said that Google Alerts had emailed her about the thread. I’m no expert on Google Alerts, but a quick look at it suggests that Mr. Waldie could have set up a Google Alert to email him whenever a new index item appeared which contained the keyword Automator. [Previous page](https://boards.straightdope.com/t/through-the-looking-glass-with-user-guides/502268.md?page=2)