an informal survey

[mountain_laurel]

my employers want me to give usage examples for the software i'm documenting. the software is, in the broadest sense, for designing electronic circuits. i'm trying to get a feel for what sort of examples people like, and see if there's any correlation with how much hardware and/or software experience they have.

[Poll #951792]

Comments

[dianec42.livejournal.com]

I checked the box for "formal training" but that was (gack) in the 1970s, so I'm not sure if it still counts. (-:

[merde.livejournal.com]

definitely still counts. one issue i have with this manual is that the audience ranges from old-school hands-on electronics guys to rank newbies who've never actually touched a circuit board in real life. i need to present the information in a way that's understandable to the broadest range of users. and that applies not just to presenting examples but to terminology and even the structure and format of the document.

i'm big on the psychology of information architecture. and if you'd told me 20 years ago that i would EVER make such a statement, i'd have laughed my ass off. and then i'd have asked, "what the fuck is information architecture?"

then again, i'd have reacted similarly to the idea that i'd be living in Texas and importing special olive oil from Sacramento because nothing less will do for my kitchen.

[madbodger.livejournal.com]

I still import my olive oil from Spain (Nuñez de Prado*) and Italy (various
Umbrian oils).

* Which I found at a big shiny new Whole Foods, once I realized that they
had changed from their old squat round-shouldered bottles with red wax
seals to tall dark squarish bottles that look like everybody else's bottles.

[catbear.livejournal.com]

Fewer grammatical/syntax words means more signal-to-noise ratio, so examples are clearer in second person.

[merde.livejournal.com]

i agree completely, but i'm curious to see whether other people prefer different methods and why that is. i know hardcore software/IT audiences intimately, so i don't have to think too hard about this stuff, but this audience may expect a different paradigm. or maybe they won't. i have no clue, which is why i'm asking people.

the VP of engineering here seems to favor the Alice approach, but i'm not sure what the reasoning behind that is; i thought it would be interesting to ask around before i try to sell him on my way. (i don't expect too much resistance unless there's a compelling reason to do it a different way; he seems to think i know what i'm doing.)

[mister-borogove.livejournal.com]

For internal design and spec docs that outline usage cases (or what agile development calls "user stories"), Alice is fine, but I think Alice has no place in a user's manual.

[whc.livejournal.com]

The Alice approach makes it sound like a training course from HR!

[dnereverri.livejournal.com]

IMHO, the Alice approach makes it look like an elementary school textbook, which some people interpret as "friendlier". If your primary audience is people who you expect to be intimidated by what you're writing about, this may not be a bad approach. If you're actually aiming at technical people, I think they'll largely be annoyed by it.

(This structure can also have its place in application manuals, if you're talking about an interaction among multiple people; moving to third person and using names can make things much clearer. For direct "you need to do this" kind of stuff, though, I think it's more distracting than useful.)

[missv.livejournal.com]

When I was writing service manuals for the big, giant machines that my husband's company builds, I tried to keep my instructions in the simplest second person voice possible. And I made sure there were lots of pretty pictures with big pointy arrows too. Because techie-types don't read anything.

[neoliminal.livejournal.com]

Yes please.

[mskala.livejournal.com]

I'd rather have instructions given in second person imperetive, like "To add a load to the voltage regulator, do this:" instead of "to your voltage regulator". If it's absolutely necessary to refer to a person doing the adding, I'm not sure whether I prefer "you" or "Alice," but I wouldn't be pleased to see either of them; it would be a lesser-evil situation either way.

I think "rails" are called that because of their appearance on old-fashioned schematic diagrams. The "+9V" and "GND" lines at the top and bottom of Figure 1 on that page are "rails." They look like train tracks if you squint your brain enough.

[mister-borogove.livejournal.com]

I'd rather have instructions given in second person imperetive, like "To add a load to the voltage regulator, do this:" instead of "to your voltage regulator".

Agree.

[whc.livejournal.com]

Me too. (or three)

[mskala.livejournal.com]

You'll also hear a signal described as going "rail to rail" if it goes all the way from one end to the other of the power supply's range. (e.g. an op amp needs to be able to produce rail-to-rail output, but many other kinds of amplifiers can't do it.) Rail to rail signals can also look like train tracks on an oscilloscope display, so when you've already got the circuit-diagram reason for calling those voltages the "rails," it further reinforces the idea. This is an interesting one because I think it's a cultural thing, like some computer-programming slang terms. I don't think I've ever heard the electrical use of "rail" explained or defined before. Electronics geeks just know what it means without being told.

[merde.livejournal.com]

somebody explained the origin of the term to me yesterday, but i've already completely forgotten what it was. fortunately, i'm absolutely certain someone on my friendslist will turn out to know.

my friends are handy like that.

[merde.livejournal.com]

yeah, i agree on that too; my example was poorly phrased.

[dglenn.livejournal.com]

I think my electronics expertise is somewhere in between "little" and "none": how about, "just enough to get myself into trouble and let the magic smoke out of things"? (I was able to explain pretty clearly -- and after looking it up on the web afterwards it turns out accurately as well -- how a thyristor dimmer switch works. I know Ohm's law, a bunch of jargon, how to add up capacitance in series or parallel, and sortakinda get why inductive loads are so much different from resistive loads. Given a schematic, I have about 1/(component count) probability of being able to make any sense of it. (I actually understood the schematics in my TRS-80 service manual!) But ask me to design an amplifier with real-world components and understand how to get a particular amount of gain, instead of a general theory-of-operation description, and I'm stuck. Ask me to design and build a circuit, and escape of the magic smoke is the most likely outcome. ... But I can use a soldering iron and make repairs. So it's kinda like my level of sewing expertise, come to think of it.)

Designing something at the level of logic gates, I think I can handle. But somebody else gets to translate from gate-symbols to part numbers and figure out where external resistors and capacitors need to be stuck on.

[madbodger.livejournal.com]

You let the magic smoke out of your SEWING MACHINE???

[dglenn.livejournal.com]

Er ... fortunately, no. But neither have I let the magic smoke out of my soldering iron; just from things I've built with it. Since (most) clothing does not operate on magic smoke, attempts to make clothes from scratch have had other failure modes, but the mental image of a tunic spontaneously emitting smoke and becoming unwearable now strikes me as so amusing that I'm not about to try to correct this any farther than pointing out that it wasn't the sewing machine that failed.

Then again, I just awoke from a dream in which there were three of me, of different ages, interacting ... and I was sorting out my financial records by putting receipts into a skillet of hot oil on the stove.

I, uh, think I'm awake now ...

[madbodger.livejournal.com]

There's always the trick of using passive voice!

[sambushell.livejournal.com]

Use active constructions in the second person imperative.

cf

Alice uses active constructions in the second person imperative.

[figmo.livejournal.com]

How about:

To add a load to your voltage regulator:
[insert list of instructions here]