gemini - kennedy.gemi.dev

💾 Archived View for gemini.spam.works › mirrors › textfiles › humor › COMPUTER › writdocd.hum captured on 2022-06-12 at 09:28:23.

View Raw

More Information

-=-=-=-=-=-=-

^S^Q

How To Write Documentation
Documentation
--------------------------
Written by: The Kid
Edited by: Bugs Bunny

One of the most important things a pirate should always do is type up as much of the information available (in a text file) about a program he is going to release. But it is also important to know what info and how best to do it. There is obviously no one
RIGHT way to do it but there are certain principles which ought to stick in one's mind while doing it.

First off, since Spelling Checker programs are now floating around, use 'em! Do you really want Doc files around with your name on them that look like they were written by a primate and a typewriter? It would also be nice if grammar and other picky things
were correct also, but this takes time and is a hassle, and most people don't give a shit. But five typos in a line (that Sensible Speller would have nailed in a minute) can drive people straight up their respective trees.

Second, keep it short! Why anyone would ever WANT to type up docs that take up 200 sectors is beyond me, but it happens. Some programs need heavy documentation, but others (like arcade-type games) don't. Many just need basics like what controls which thin
g on the screen. Typing in the cute stories that are in original doc or in a review is often pointless and wastes diskspace, on-line time, paper and sanity. Reading the story line of some of these (Rescue on Fractalus comes to mind) has made me toss my co
okies more than once.

Third, is there REALLY some point to this:

+-------------------------------------+
! Babbling Baboons From Siberia !
! ! More Pointless Gibber
! Documentation By: Bozoid Creepo ! Over Here
! !
! Special Thanx To: The Burnout, !
! Temper Tantrum, and Spike !
! !
! Call These Rad Boards: !
! The WhoreHouse-------999-321-DUMB !
! The FBI--------------202-946-0701 !
! The Outhouse---------555-302-1010 !
! !
! To The Blaster: Try Fucking A Small !
! Heina with your -------- !
+-------------------------------------+

And so on. What is it about making text frames around stuff? Some bright people have gone so far as to put ALL the docs in these cute frames. The above illustration is minor, in an attempt to save space on THESE docs. Do some people receive some sort of p
hysical pleasure from going through the hassle of framing everything and creating dazzlingly dull ASCII displays?
1) Take Credit but don't get out of control!
2) Don't Thank everyone's cousin.
3) Don't Advertise every board you've ever logged onto! (And don't do it unless the Sysop likes it!)
4) Keep the Personal Shit in your own temperamental little heart.
5) Don't hit Return 26 times to finish a paragraph.
Try This Instead:

Babbling Baboons From Siberia
Written by: White Knight
Thanks to: Dirt Breath and The CrunchLine AE (303)707-QUIT

Fourth, don't forget key info! If the damn thing has to have 128K to work, how about a little mention of THAT! (Gato Docs spring to mind here.) But, again, don't lose your mind including it:

Control-S (CTRL-S) - Hitting the CONTROL (CTRL) key and S key together will turn off the sound. Repeating this procedure will turn it back on.

Yeah, right. Just because the company thought it was writting for a six year old who never used a computer doesn't mean you have to write that way! Think, the people who'll be reading your docs are probably able to figure this out:

CTRL-S Toggles sound

You gotta assume the idiot reading your docs will be able to make the connection between the swinging baseball bat and the sharp pain they all of a sudden feel. Otherwise you'll be there all day telling them the correct way to press and depress the keys.
(And if they can't figure it out, advise them to go back up into the trees and evolve some more.)

Fifth, although a lot of people are not operating at 80 columns, most of them have some way of converting 80 col text to 40 or whatever, so it is probably better (when possible) to write the docs up in 80. This is not terribly important. But if you do pic
k a margin - stick with it! And it probably is better not to end every line with a carriage return so it can be printed easily in whatever format by the end user. Suit your tastes, but since you are probably doing this out of the goodness of your scheming
heart, why not make it easy for the final user to manipulate the file easily?

Sixth, along the same line - DON'T leave YOUR printer and word processor codes in a file! Fascinating things are bound to happen feeding Epson codes through a C. Itoh or Magic Window commands into AppleWriter! Sometimes nothing happens (too bad!). Either
way someone is going to have to clean up after you and mommy doesn't like the computer so you might as well get to it.

Seventh, make sure the docs file stays with the program. On the same disk is truly a revoutionary concept but sometimes this won't work (with programs that have no space or are modified on disk). This thing may get passed out by forty or fifty people/boar
ds (and you can't make them do it right) so it would help if you made sure the first copies go together. One way is to name the thing in recognizable manner:

T 062 BABBLING BABOONS DOCS

Along that line, it really is mindless to go insane over telling people you uploaded it:

T 062 BABBLING BABOONS DOCS U/L BY GODALMIGHTY.!.1

People are going to be trying to get it right forever. And they don't CARE who did it. They just want the damn things! It's nice to get your name spread upon the lips of the multitude but they're probably saying, "That goddamn shitforbrains, why did he ty
pe all that crap?" Is this the reputation you are cultivating? (Ok. Don't answer that. Most of you lowlives WANT to be known as Glorious Leaping Twerps From Saturn. You can't be saved. Get a frontal labotomy, it might do wonders for my sanity)i

Lastly, if you've been digging into the program and have some unique patches or locations for particular functions put the technical info in also. Sometimes it is best not to go patching a program before passing it along but giving out the data is appreci
ated. Maybe they do want their characters to never get killed, even by Big Slimy Venusian Prostitutes With AIDS, but maybe they actually want to be challanged (as opposed to just sitting there with the white flaccid flesh hanging from their vegetating bon
es always winning even though a small tortoise would play the real game better).

While this is not strictly a documentation idea (it's more about programming), it is important because getting patched programs without info about how to remove the patch will kill the fun for anyone not like you. (I know, that's the fun part for some of
you. Go crawl back into your cages. We'll let you out if you stay on the paper.)

Remember though: it ain't really necessary to throw in a 200 page Source Code listing at the end of the general docs! If you've got TONS of technical notes, make them into a tech file separately. The bafoons who can't understand it and can't use it will p
ray for your soul (though it was probably a lost cause when you were a wee cribcrawler) in thanks. [Of course, if it's an Assembler or something the Galoping Twit Brigade won't be using it much either way.]

Really finally, don't keep insulting your readers... Oh, well. So I don't listen to my own advice...

Coming Soon:
1) "How To Walk Using Both Legs And No Hands"
2) "How To Eat Without Losing a Major Sensory Organ"
3) "How To Look In A Mirror Without Throwing Up"
4) "How To Close A Zipper Without Becoming Sterile"
And our self-help analysis book:
5) "A Gibbon Can Do It, Why Can't I?"