RtFM (When All Else Fails) by Domenika Marzione [documentation]

[miss-porcupine.livejournal.com]

Technical writing, to paraphrase Daniel Patrick Moynihan, is all about defining common sense down. On the surface, it's all about writing out directions. But tech writers know that the real job is coming up with the myriad ways someone can screw up the task and then telling them explicitly how not to do it that way. Just in nicer language.

Codifying existing practices takes that theory and turns it into object lessons -- every explicit instruction has a basis in fact, not imagination. You're not telling folks not to do something, you're telling them not to do it again.

Remember -- it wouldn't be in there if someone hadn't tried it first.

RtFM (When All Else Fails)
Genfic, rated PG (for Pure Guano).

GPM 003 -- Encountering New Artifacts HTML | LJ

ATLPM 010 -- Cataloging New Artifacts HTML | LJ

With a tiny fist raised in solidarity with all those who know that the more educated the intended audience, the smaller the words you have to use. Thanks to aliciam and smittywing for following along.

Comments

Significant Digits

[smittywing.livejournal.com]

Note: Before sending any artifact to AT Lab I, consult the Expedition Manifest to make sure that the unknown object is not something brought from Earth.

This continues to be my favorite part.

Is the example description of Rodney's personal shield?

Re: Significant Digits

[miss-porcupine.livejournal.com]

It is Rodney's shield, but only from memory and not from actually going back and looking at it.

And the Earth line came about because Rodney made someone cry for bringing him the bottom end of an emergency lamp or something akin. :)

[rokeon.livejournal.com]

Remember -- it wouldn't be in there if someone hadn't tried it first.

*laughs* It's like every line is a little ficlet of its own. I imagine most of them end with Rodney shouting.

(So much love for the bits on naming and checking to be sure it's not from Earth. Because they may be geniuses, but that doesn't mean they aren't idiots. So much love.)

[miss-porcupine.livejournal.com]

That little bit up top, with the smart-people-needing-tiny-words? NOT KIDDING. REALLY NOT KIDDING.

Glad you enjoyed.

[kajikia.livejournal.com]

Ha! Very amusing. I like the feeling that everything in this manual has been learned the hard way, especially the repeated references to not turning anything on to identify it. And the checking to make sure it's not from Earth really is hilarious--I can totally see that happening.

[miss-porcupine.livejournal.com]

Sadly, there is no such thing as not repeating things often enough. Even in an academic environment such as Atlantis, where you don't need to run everything through the gauntled of lawyers to check for liability issues, the minute you DON'T explicitly tell someone not to do something harmful, it will be done and they will say "but it didn't say not to".

Thanks for the comment.

[misty4me.livejournal.com]

But tech writers know that the real job is coming up with the myriad ways someone can screw up the task and then telling them explicitly how not to do it that way. Just in nicer language.

Oh.My.God this is my life. I'm a tech writer.

What does it say about people that you have to preface a set of instructions with the phrase, 'Perform the following instructions in the order they are written, beginning with step 1'?

[miss-porcupine.livejournal.com]

I'm with you. I automatically start documents with instructions on which program to use because while it's actually impossible to do Task A in Program B, that doesn't mean a half-dozen people won't try it just because they like Program B better than Program They Should Be Using.

It's funny when it's fictional, though, right? *smiles weakly*

[misty4me.livejournal.com]

Oh yeah. LOL, it is funny in fiction, especially since it's not me having to explain why that six year old software that isn't supposed to run in XP can't just be loaded on the new machine that they 'just had to have to get my work done.'

[redhawk.livejournal.com]

Computers count from zero, therefore, so should you.

;)

Redhawk,
a Unix sysadmin

[adannu.livejournal.com]

HEE. I love this. :D Especially the part about calling Sheppard if the artifact's Doing Anything Especially Dangerous Things.

[adannu.livejournal.com]

PS -- All tech writers (and Rodney) should have one of these babies. http://www.thinkgeek.com/homeoffice/mugs/299a/

;)

[miss-porcupine.livejournal.com]

It's funny, but at the same time... what else are they going to do? :)

[cofax7]

Oh, these are great.

[miss-porcupine.livejournal.com]

Glad you enjoyed. :)

[raisintorte.livejournal.com]

These were great!!

I loved this: Note: Before sending any artifact to AT Lab I, consult the Expedition Manifest to make sure that the unknown object is not something brought from Earth.

And including a link to the camera manuel? Perfect!!

[miss-porcupine.livejournal.com]

You know Rodney made someone who brought an Earth object to him cry like a baby. Or else they made Rodney cry like a baby at the stupidity of it all. Could go either way.

Thanks for the comment.

[dzurlady.livejournal.com]

I love this, because that is so the way it would work. You can almost *taste* the despair behind it. :) Plus, the acronyms! The databases! The constant reminders to save it to the network! The orange stickers! This is fantastic. :)

[miss-porcupine.livejournal.com]

If this document could talk, oh, the stories it could tell. (Conversely, the poor shlub who got stuck writing the document, oh what stories he could tell...)

Glad you liked.

[rivkat.livejournal.com]

This is great. I agree that the camera manual was a beautiful touch, as well as the mailto link.

[miss-porcupine.livejournal.com]

First rule of tech writing on the intranet/internet: always, always provide clickable links to anything you want people to read/do or else they won't. :)

I'm happy you liked.

[neonhummingbird.livejournal.com]

< snickering > The tech writers of the world salute you! Both of these are awesome examples of one of the things I like best about your fic -- the constant attention to real-world details. I, too, can picture the poor schlub writing this -- or, actually, the poor schlub going back to work on v3.2.1 as people come up with newer and more creative ways to screw up and Rodney's blood pressure shoots ever higher...

[miss-porcupine.livejournal.com]

Sadly, most of the time I, too, am one of the poor shlubs writing this. (We won't discuss the eery similarity between these documents and what's currently open here at work.)

Almost everything here probably is Rodney-inspired, but he's perpetrator as much as victim. :)

Thanks for commenting.

[zoerayne]

Fabulous!

[miss-porcupine.livejournal.com]

Thank you!

[livrelibre.livejournal.com]

As someone who has had to write documentation for work, this provided a wealth of *headdesk*ing fun. Thanks!

[miss-porcupine.livejournal.com]

All tech writers of the world, smite! unite! Glad you enjoyed.

[diluvian.livejournal.com]

Do not go beyond two (2) significant digits.

Heeeeee! Oh, god, of *course* that needs to be limited!

[miss-porcupine.livejournal.com]

After the unfortunate incident with Dr. Perotti and the sonar amplifier weighing 4.938517263353 kilograms, yes. There had to be a limit.

[twoweevils.livejournal.com]

...the more educated the intended audience, the smaller the words you have to use.

YES!! Oh, so true, and so sad.

These were very good examples of trying to cover every base, because you just know that if you leave a loophole, someone will stick his head through it, usually with dire consequences. (Why yes, I do speak from experience.)

Great work!

K.

[miss-porcupine.livejournal.com]

I, too, write from experience (it's vaguely therapeutic, but not quite enough). Glad you got a giggle.

[wychwood]

Heh :) I like. Especially the repeated instruction to send anything dangerous to Sheppard *g*

[miss-porcupine.livejournal.com]

It's funny, but at the same time, what else is anyone going to do? (Besides sit there and stare at it.) :)

[marag.livejournal.com]

Heh. I've done my share of technical writing and this feels oddly familiar ;) Very funny!

[miss-porcupine.livejournal.com]

Thanks. :)

[milenaa.livejournal.com]

This is so neat!

[miss-porcupine.livejournal.com]

Glad you liked! :)

[mercuriosity.livejournal.com]

I love this! It's so much fun trying to extrapolate whole mishaps from a single, sterile line in a tech manual. :)

[miss-porcupine.livejournal.com]

Yah. Oh, the stories the writers could tell... Thanks for commenting.

[ex-nilahasi174.livejournal.com]

I love this. Especially: "They should not include speculation about the purpose of the device or use subjective terms such as "palm-sized" or "ugly.""

Awesome job! :)

[miss-porcupine.livejournal.com]

Thank you very much. And you can just imagine what sort of subjective terms were used... :)