Showing posts with label documentation. Show all posts
Showing posts with label documentation. Show all posts

Monday, March 9, 2026

To Find Treasure, Read an Enchanted Scroll

He recommended that I write my documentation in TeX (“tech”), a typesetting language developed by Donald Knuth. As a result, I was hired by a medical records firm deeply invested in TeX for documentation. As it happened, TeX was the basis for SGML, the Standard Generalized Markup Language. SGML became HTML. In the meantime, I served as the secretary of our local DECUS chapter and produced the quarterly newsletter in TeX. In addition to writing the system maintenance manual for a MicroVAX, I also documented the game of Moria on the VAX using TeX. When HTML was invented, it was pretty easy for me to figure out. — https://necessaryfacts.blogspot.com/2013/08/claude-m-watson-1922-2013.html

"One of the major areas where TeX holds its own is as a “back end” to SGML and XML systems, where no human intervention is expected between data input (structured, not WYSIWYG) and removing the output from the printer or viewing it on a screen. Granted, this isn't “creative” in the sense most often discussed, but it's still important to the readability and usefulness of such documents that care is taken with the design and typography, and the flexibility and programmability of TeX makes that possible.

"In summary, TeX is a special-purpose programming language, and the program that interprets the language, that is the centerpiece of a typesetting system that produces publication quality mathematics (and surrounding text), available to and usable by individuals." https://www.tug.org/whatis.html


CTAN: The Comprehensive TeX Archive Network 

- https://ctan.org/tex?lang=en



%This is written in Donald Knuth's  \TeX 


\font\reg=amr10 scaled\magstep1

\font\ty=amtt10 scaled\magstep1

\font\sl=amsl10 scaled\magstep1

\font\it=ammi10 scaled\magstep1 

\font\nt=amssbx10 scaled\magstep0 


\def\nl{\hfil\break} 

\def\cl{\centerline} 

\def\ll{\leftline} 

\def\rl{\rightline} 

\def\p{\indent} 

\def\ub{\underbar}


\reg

\cl{A guide to {\nt{Rogue: The Dungeons of Doom}}}

\vskip.1in

The game of {\nt{Rogue}} was developed by Michael C. Toy, Kenneth C.R.C. Arnold, Jon Lane and Glenn Wichman.  Jon lane adapted the game for the IBM-PC.  It is marketed by Artificial Intelligence and Epyx.  This copy is pirated.


The object of the game is to fight your way down 26 levels to retrieve the {\sl{Amulet of Yendar},} then bring the Amulet up to the surface.

\vskip.1in


\ll{{\ty{\ub{Keyboard \& Keypad}}}}

\vskip.1in



You move left, right, up down and diagonally by using the cursor control keys on the numeric keypad.  To strike a monster, move into it.  If the monster is to the left, use the left arrow key.  Some {\ty{qwerty}} keys will also move you.


Function key {\ty{F1}} is {\ty{Help}.}


Function key {\ty{F3}} is the {\ty{Repeat}.}  If you want to throw a bunch of darts, press numeric keypad $+$ {\ty{(plus)}}, then the direction key, then the {\ty{qwerty}} key that corresponds to your darts.  To repeat the throwing sequence, press {\ty{F3}.}

 

Function key {\ty{F9}} is programmable. If you press {\ty{F9}} you will see the version number.  You can then key in {\ty{ALT-F9}} to program it, for instance with 3s to search the same place 3 times.


Function key {\ty{F10}} is the {\ty{Boss Key}.}  Press it and the screen goes blank and shows the MS-DOS  {\ty{C>}} prompt.


The {\ty{Del}} key is for waiting.  The {\ty{Ins}} key takes you down a stair case.  {\ty{Scroll Lock}} turns on {\ty{Fast Play}.}  You will dash down hallways and across rooms.


Pay close attention to {\ty{CASE}.}  UPPER CASE `T' means `Take off Armor' while lower case `t' means `throw weapon'.


\settabs 4 \columns

\+&{\ty{Key}}&{\nt{Function}}\cr

\vskip.1in

\+&{$+$}(plus)&throw weapon\cr

\+&{$-$}(minus)&zap with wand or staff\cr

\+&{$<$}&go UP stairs --- if you have the Amulet\cr

\+&{$>$}&go DOWN --- same as as {\ty{Ins}.}\cr

\+&e&eat\cr

\+&i&inventory\cr

\+&T&Take off armor\cr

\+&W&Wear armor\cr

\+&P&Put on ring\cr

\+&R&Remove ring\cr

\+&r&read a scroll\cr

\+&q&quaff a potion\cr

\+&w&wield a weapon\cr

\+&d&drop something\cr

\+&s&search\cr

\+&S&Save game\cr

\+&t&throw weapon\cr

\+&z&zap with wand or staff\cr


You can {\ub{repeat}} an action by keying in numbers.  10s means `search this spot 10 times' and 17{\ty{Del}} means `wait 17 turns'.


\par\vfill\eject


\ll{\nt{Statistics}}

\vskip.1in

At the bottom of the screen, you will see what Physical Level you are on, how many Hits you can take, how much Strength you have, how much Gold you have accumulated, the strength of your Armor and what your Experience Level is.


Also, hidden in the software are other stats typical of D-and-D games: such as your dexterity and luck. 


Your Experience Level increases with the doubling of experience points.  You get, say, 1 point for killing a Bat and 20 or so points for killing an Aquator.  At the start of the game you have 10 Experience Points.  At 20 points, you increase your Experience Level and Hit Points.  Also at 40, 80, ..., 2560,... 


When you die, your rank is determined by 90\% of the Gold you have found.

\vskip.1in


\ll{\nt{Hademetry}}

\vskip.1in

Generally, each level is layed out as a 3-by-3 array of rooms.  As you move lower and lower, this is mutated.  Rooms are replaced by mazes or hallways.  At any level, one or more room will be missing.  You will develop a sense of rightness, a feel for whether or not there should be a room or a passage.  A wall of a room will look solid until you {\ty{s = search}} along it.

\vskip.1in


\ll{\it{Scrolls}}

\vskip.1in

Scrolls are made up of random syllable that change with each game. {\it{Glows\ blue}} means enchant weapon or armor. {\it{Red \ hands}} is confuse monster (after you hit it).  {\it{Maniacal \ laughter}} is scare monster and the laughing means you wasted the scroll.  You have to stand on this scroll.  When facing a tough guy, like a Troll or a Jaberwocky, {\ty{d = drop}} this scroll and the monster will not harm you.  Try to pick it up again and it crumbles to dust.  {\it{High \ pitched \ humming}} is aggravate monsters: they come looking for you.  {\it{Someone \ watching \ over \ you}} is remove curse and you can deal with cursed armor or weapon.  There are also Teleport, Identify and Create Monster.  If a scroll seems to do nothing, it is probably Hold Monster and you must have a monster in the room or hallway with you.  The blank scroll does nothing. 

\vskip.1in 


\ll{\nt{Potions}}

\vskip.1in

Potions come in colors (including plaid!) that change with each game.  They can restore your strength ({\nt{`warm all over'}}), heal you, poison you and blind you, increase your Experience Level, and allow you to see monsters, magic, and food in other rooms. {\nt{Mango juice}} is  `see invisible' which allows you to perceive otherwise invisible Phantoms and will also cure blindess.  (Healing and Extra Healing will also cure blindess.) 


\par\vfill\eject


\ll{\nt{Rings}}

Alas, there is no ring to rule them all -- which is probably just as well: it would only corrupt you.  Rings use up food.  Cursed rings include {\nt{Aggravate Monster, Teleportation, Negative strength, Negative damage, and Negative dexterity}.}  Good rings include {\nt{Stealth}} (for sneaking up on otherwise awake monsters), {\nt{Slow digestion,}} and {\nt{Positive strength, dexterity, etc}.} A scroll of {\it{Remove \ curse}} will allow you to Remove a cursed ring.

\vskip.1in

\ll{\sl{Wands and Staffs}}

\vskip.1in

Wands and staffs are made of various metals and woods.  They work the same kinds of magic.  In one game a Mercury Wand will be Haste Monster; in another game Haste Monster will be and Oak Staff.  There are also lightning, cold, Hold Monster, teleport to, teleport away, slow monster, light, striking and magic missile. 

\vskip.1in 

\ll{\nt{Weapons and Armor}}

\vskip.1in

Dagger, spear, bows and arrows, bolts, mace, long sword and two handed sword.  Clearly, the larger the weapon the better it is. If you wield a bow, it will increase the effectiveness of an arrow you throw (unless the bow is cursed, of course).

\vskip.1in

Leather, studded leather, ring, chain, banded, and plate.  The heavier it is, the better it will protect you.  There is some leeway in this.  Obviously, ring mail with a rating of {$+3$ \ 7}  is better than plate mail of {0\ 4.} Cursed armor is always a drag.  Wearing (or carrying around) heavy armor uses is food but is generally worth it.  Interestingly enough, if you Win the Game and cash in at the Thieves' Guild, they pay well for armor because it doesn't do you any good while you are fighting your way ``there and back again''.  That is, carrying around five suits of plate mail won't do you as much good as a couple of staves of Lightning, a Scare Monster and a couple of Extra healings.  If you get the Amulet of Yendar, you can load up on armor on your way back up the stairs.


Aquators rust armor.  Aquators cannot rust Leather.

\vskip.1in


\ll{\nt{Monsters}}

There are 26 of them, from Aquator to Zombie.  The lower you go, the uglier they get.  Leprechauns steal your gold and Nymphs steal anything in your inventory. Get across the room and shoot them with arrows.)  Vampires make you weak and Wraiths drain away your Experience.  Rattlesnakes take your Strength.  (There is a wand of {\it{Cancellation} } which will negate those powers.)


\ll{\nt{Summary}}

\vskip.1in

There is more to the game.  The above should get you started.  There have been some interesting theories about the design philosophy.  For instance, the game knows the {\ty{ROGUE.SRC}} scoreboard file and will set the environment accordingly.  Do not expect to find the Amulet of Yendar on the first try: you have to establish a track record.  Some believe that it is the number of steps you can take before you die, or the level you will die on, is fixed when the program starts. Other believe that there exists a maximum allocation of your magic you can win the first time you play.  Indeed, those who have played Dungeons and Dragons tend to do better at Rogue than those who do not.  

Good luck. 


\bye 



PREVIOUSLY ON NECESSARY FACTS

Ruby Methods the Ruby Way 

Digital Literacy and Artificial Intelligence

Visualizing Complex Data

Knowledge Maps

Fortune Cookie in Hex Code



Friday, February 20, 2026

Cover Letters for Resumes

 This is how my typical cover letter starts out when I deliver it as a PDF in a drop box on an employer’s job site.



I write out the full name of the state. If there is an envelope for a printed letter, that carries the standard two-letter USPS abbreviations because envelopes are sorted by machines. But our states have nice names, many of them from Native languages, others founded on traditions that express hope for the future: New York, New Jersey, New Mexico. 


As my resumes morph by the hour adapting to sporadic suggestions of what is best right now, for the cover letter, I stand fast by the traditional format for a real letter. 


Most people want to shape their public selves into an acceptable image. (The formal study of impression management originated with Erving Goffman’s The Presentation of Self in Everyday Life; 1956, 1959). And I understand that. I also know that sooner or later they are going to find out the truth, so you might as well be upfront about it. 


I am a writer. I like writing. I like to think that I am good at it. I take words seriously. I believe that much verbal understanding develops subconsciously by the continuous integration of events in context. We understand the traffic sign PED XING because we long ago accepted XMAS. However, those are temporal regionalisms that might not cross into your reader’s worldview. (Even though I know the word “Weltanschauung” I did not use it there where it could have held a lofty place.) 


I have met other technical writers who do not criticize their own work. They trace a wiring diagram or a pipe flow and what they say about it is delivered to the reader without any further challenge. I always ask myself: If I did not grow up here and now—If I never saw this machine opened up—If I were new to this interface—what would these words say to me about that? 


Most teams looking for a technical writer want to make sure that I have continuous and direct experience in whatever their current platforms happen to be. They seem not to care if my work is understandable to their clients. I am sure that the hiring team will look at my submission and judge for themselves how well I write but that is another local-subjective fallacy because those managers will not be the ultimate consumers of the works which I create. 


In our world, we accept prima facie that money declares its value in units of account: Five $5 Dollars; Quarter Dollar. That is a relatively recent invention. The traditional gold pound sovereign coin of the United Kingdom now with the image of Charles III still has no unit of account on it. American numismatists know a somewhat rare colonial Connecticut coinage, privately issued by the owner of a mine. The motto reads: “I am good copper value me as you choose.”


Dear [Employer Name]:

Profitable documentation turns the reader into an actor in a story. The best documentation is an asset that is portable and extensible. It can be translated without muddle.
  • I have done this for json scripts, fluid piping, industrial controls, and regulatory compliance. 
  • I crafted white papers and blog posts for managers and made single sheets to be hung on machines for operators. 
  • I interviewed engineers to create procedures that read at a sixth-grade level for a multi-processor industrial controller. 
  • The State of Kansas used an article that I wrote on the future of money as part of their standard 11th grade literacy test.

As a freelance writer, I have published business profiles about 

  • laboratory and electronics developers
  • musical theater
  • flight instructors
  • retirement communities
  • and restaurants. 
My focus is on the ultimate consumer, the person who will be applying the information to their work. 

As a member of the Texas State Guard for five years, I taught the WebEOC emergency management platform. My client learners included frontline computer operators and their commanders in the general staff. 

As a public programs presenter at the Ann Arbor Hands-On Museum, I created and delivered presentations in kitchen chemistry to mixed audiences. Researching the life of the first working scientist to publish a science fiction story, I told the story “From Texas to the Moon with John Leonard Riddell” as a magazine article and as live performances at both numismatic and science fiction conventions. 

Your clients and their customers will benefit from the fact that I am flexible, innovative, adaptable, and creative. I keep track of my goals and I make my benchmarks. I work well in a complex and changing environment. I look forward to discussing with you the talents that I can bring to you, your clients, and their community.

Thank you for your time and consideration.

Sincerely,
/s/

Michael E. Marotta


 Dear [Employer Name]:

You need someone who can start training your AIs for documentation. I can do that. I took a class in ChatGPT through LinkedIn Learning and I now work tutorials in AI concepts from Brilliant. I am currently editing a book of science fiction stories set in Austin 2078. Of course, I have decades of experience in technical writing. The most recent ten years of that is on my resume. You need someone who can say, “I have seen the future and it works.” 


That was said by an apologist for Russian Marxism. So, no, that future did not work out well but Lincoln Steffens was enthusiastic. And you need someone who has the spirit within: en-theos-astic. 


The job description and qualifications did not ask for evidence that my writing is readable. You will evaluate the samples I sent but I must ask: against which standard? 


I created procedures for a multi-processor industrial controller at a sixth-grade reading level. The operators must understand the Help and the engineers should grasp it at a glance. I placed a peer-reviewed article on numismatics with the British Association for the History of Astronomy. It read at a 10th grade level. Astronomers usually read at a university level but this was new information for them from a different but equal discipline. The State of Kansas used an article that I wrote on the future of money as part of their standard 11th grade literacy test. I wrote that article in 1995. You will find it included in this application. 


My master’s degree is in social science. Although I am not gregarious, I interface well with development, production, administration, and sales because I take a sociological viewpoint of other cultures. On the Myers-Briggs, I am right down the middle for INTJ / ENTJ. 


=> People with NT preferences … typically take a “what else can we do” approach to leadership. They tend to consider new ways to address tasks and projects, and often have an innovative mind-set that is about changing things up to make a situation better. — https://www.themyersbriggs.com/en-US/Access-Resources/Articles/leadership-and-the-intuitionthinking-nt-process-pair


As a freelance writer, I have published business profiles about retirement communities, political lobbyists, laboratory and electronics developers, musical theater, and restaurants. My focus is on the ultimate consumer, the person who will be applying the information to their work.


As a public programs presenter at the Ann Arbor Hands-On Museum and at the Texas Museum of Science & Natural History, I created and delivered shows in everyday science to mixed audiences. Researching the life of the first working scientist to publish a science fiction story, I developed the story “From Texas to the Moon with John Leonard Riddell” as a magazine article as well as live performances at both numismatic and science fiction conventions.


I held the rank of petty officer 2nd class (E-5) in the Maritime Regiment of the Texas State Guard. Previously assigned to training and development where I wrote plans and tracked performance, my final post was to be the regimental public affairs officer. As the PAO, I managed our Facebook page.


I worked for Kawasaki and Honda after taking a college class in Japanese for business. At Honda, just “Ohayo gozaimasu” in the corridors was enough. At Kawasaki Robotics, while teaching operations and programming, I also translated parts lists; I even answered the phone one night and routed the call. 


I worked for three German firms: Carl Zeiss IMT, EOS North America, and Kapsch Trafficom. For Zeiss, I translated an engineering booklet from German to English for our office in Detroit. Here in Austin, I did most of the work for EOS with Google Translate which I checked for correctness. I took German from the 7th grade through my sophomore year in college. When I was in the ninth grade, I entered a speech contest. Registering late, all of the slots were taken except for Native Speaker. I took first place. But that was then and this is now. Es ist eine lange Weile gewesen seitdem ich Deutsch gesprochen habe. 


As the AI named Wintermute said to the hacker Flynn in the novel Neuromancer by William Gibson, “Minds are not read. You still have the paradigms that print gave you.” I have been working on this problem for a long time. I can deliver what you need.


Sincerely,

/s/


Michael E. Marotta


ON TECHNICAL WRITING

Documentation is Specification 

Readability is the Only Metric 

Technical Writer Job Description 

Knowledge Maps 

Visualizing Complex Data 


PREVIOUSLY ON NECESSARY FACTS

An Online Class in Astrophysics 

Base 7 

Observing With NASA: An Open Platform for Citizen Science 

Science versus Common Sense