Sunday, September 27, 2009

Shulchan Aruch and Technical Writing

When I first started studying Talmud, I thought it made a lousy technical manual. I fairly quickly understood that wasn't its purpose. The codes - the Mishneh Torah, the Shulchan Aruch, the Mishna Berura - that is where I would find decent tech writing, I decided. The memories I had of studying the Mishneh Torah just post bar-mtizvah reinforced this impression.

Years past, and I finally began to study the Shulchan Aruch. My first thought was - wow! the craft of tech writing has really advanced since this book was written. But eventually I came to the conclusion that one of the major problems was the way revisions to the SA were handled.

This is how it would go, IMO, if we did software manuals the Shulchan Aruch way.

The Microsoft Word 1.0 manual would be made by consulting the manuals for WordPerfect, Wordstar, and Notepad. Majority would rule, except where it wouldn't. Shortly after the first edition came out, some tech writer for one of the computer magazines would produce a fisked edition which would quickly become the standard. Other people would take this now standard text and hyperlink their commentaries to it. When new releases of the software came out the old text would be left unaltered, but new hyperlinks would be added. It would like like this:

Shulchan Aruch To exit the program, press Alt F4 Rema: And there are those who say that it is better to press Alt F and then Alt X and this is the custom and should not be changed

[Tons of other commentaries here]

[6 hyperlinks from the Shach which point to earlier comments in the Shulchan Aruch]
Shach It is best to save before exiting, but if one did not do so when the program asks if the text should be saved one should reply yes. In a case of great need, for example if one has completely screwed up shortly before the deadline one may exit without saving.

[On the other side of the page in a different font]
Taz The M"A has an alternate method of closing, which is preferred.

[To be really accurate this reference should be on another page entirely, but I'll spare you]
Magen Avraham: Hitting Ctrl Q requires fewer keystrokes to exit and hence is preferred.

1 comment:

Anonymous said...

LOL. Should have saved this for a Purim Torah