Xah Lee, 2010-04-18, …, 2010-08, 2011-03-17
… my writing is razor blades in hot buns to grammarians, chocking dagger to mouthing moralists, logic bomb to irreflecting morons, eye opener to epochal theorists, immaculate calculus to logicians, euphoric oxygen to English masters, orgasmic honey to poetic chicks. That is to say, when i wanna be on the right occasion, too.
you see, English under me is like a love slave. I say jump and she jumps, I say kiss and she kisses. And when i need to vent, she bends double and pleads cum. Of course, it is not to say my theories are unerring or i'm impeccable or sans foibles and grammatical trespassing. But all things considered …
– Xah Lee, 2005-06
This page is a preliminary essay that describes the writing style of Xah Lee (me) on XahLee.org. The style is roughly based on simplicity and consistency with respect to computer parsing and human readability, for writings that are tech tutorial or expositions. In essay or creative writing contexts, in addition to that, unusual constructs, esoteric jargons, figure of speech, etc are used sans qualms against the writing establishment.
This page describes the style used on xahlee.info and or my online posts. It does not represent the style used for business or other public writing.
The article “an” is always written as “a”. (See: To An Or Not To An.)
“I” is always written in lower case “i”, unless it is the first letter in a sentence. (See: On “I” versus “i”)
In tech writing, sentences should be as short as possible; the parsing complexity should be lowest possible. In many cases, this means breaking a sentence containing “however, that is, but, and”, into 2 separate sentences. In creative writing, sometimes make sentences as long as possible with such conjunctions.
In contrary to popular writing advices, do not always use active voice. In particular, in tech or math exposition, always use passive voice. The text should be as cold and inhuman as possible. (e.g. Nicolas Bourbaki) In general, do not address the reader in any way. In some of my tech tutorials, i started to address the reader, as a way to prostitute my writing to make my site more popular for monetizing purposes. (See also: What's Passive Voice? What's Aggressive Voice?.)
In contrary to popular writing advices, do not fully spell out numbers such as “two cups” or “in the year of our lord two thousand and ten”. Write “2 cups” or “in the year of our lord 2010” instead. If a number starts a sentence, full word can be used if otherwise it is confusing.
In tech writing contexts, spelling should be the more logical or simple variation. e.g. “color” instead of “colour”, “dialog” for “dialogue”, “programing” for “programming”, “criterions” for “criteria”, “polyhedrons” for “polyhedra”.
“Logical” here usually means that the form corresponds to pronunciation, or the form has a simpler morphology, or with more regularity.
In literary contexts, the choice depends on the desired effect.
Also, in some cases, i take the initiative to rectify english thru common writing. Examples:
The frequency of these usage depends on seriousness and audience of the writing. The more serious the context, the less of these intentional errors. They are meant to be masked as occasional misspellings or typos.
Do not use a “and” for the last item in a sequence of things, unless it is too odd. For example, write “My favorite fruits are peach, banana, cherry”, not “My favorite fruits are peach, banana, and cherry”. In literary contexts, make use of the conjunction if the last item is to be emphasized.
Also, where there is a parallel sequence, do not add the phrase “respectively”. For example, write: “peach, banana, cherry, colored pink, yellow, red.”. No “respectively” there.
In tech tutorial or math exposition, use the most basic words only (A vocabulary of ~1200 words (note: Basic English has 850 words)).
When i have time, avoid any idiom, even basic ones, by rephrasing it so that the meaning can be understood by non-native speakers. This is done by using unambiguous constructs, and use words that do not have many meanings, and use logical style. Examples:
In essay or literary work, arcane, abstruse, erudite, words, idioms, figure of speech (allusion, alliteration, antithesis, cacophony, hyperbole, homonyms, homophones, parallelism, simile, pun, allegory, parable, irony, innuendo), format (e.g. deeply nested parenthetical writing (like this)), etc, are employed at will so that when read by a English expert, it is of maximum fluidity plus clarity, but meanwhile implicitly insults grammarians, pedants, academicians, moralists.
For example, if they are British, use mixed Brit and American spellings. If they are American, use Brit spellings for choice words, e.g. “this bloke's got square brain and round arse.”. If the forum is discussion of english idioms and a particular is pedantically annoying and aggressive, in my response i might fill every sentence with decorative idioms, such as starting every paragraph with “On the other hand; By the way; In a way; At the end of the day”. If it is a poetry forum, might write in a cold calculus style in the extreme, yet make it alliterate. (Sample title: “The Calculus of Poesy”)
The more esoteric the usage, the skill to wield, the linguistic background required, the symbolic logic of discernment, the size of vocabulary, knowledge of etymology, niche of lingoes, to appreciate, the better. If they are educated, exploit word etymology, usage history, linguistics knowledge, etc, so that the resulting style is contrary to the specialized wont to see. So that when they deem you a idiot caused by your style, actually they are. For example, for the general programer audience, over the years many tried to correct me with good intentions in private about how “programing” should have 2 m, unaware that single m is found in every dictionary as accepted variation. Majority will simply make a fool of themselves in public.
Note: the meaning or intended effect, should never be sacrificed.
If you are learning technical writing, i recommend: Simplified English.
3 types of dash are used.
Any other type of dash (en-dash, etc) are not used. Also, word is never cut into two by hyphen for justification purposes.
The apostrophe symbol is always a straight one (ASCII 39), not curly one. For example, “I'm”, “Mary's”.
The symbol for quotation is always written using matched curly double quotes “like this”, and not straight quotes.
When quoting a text or a person's speech, the text inside a quote represent the exact speech; any punctuation not in context of the speech is not to be included inside the quotation. This is in contrast to UK style. For example, the opening paragraph of Alice is:
… , ‘and what is the use of a book,’ thought Alice ‘without pictures or conversation?’
It should be:
… , “and what is the use of a book”, thought Alice, “without pictures or conversation?”.
Note the double curly quote, and period at end of paragraph.
Another example from Time Machine chapter one:
“That is all right,” said the Psychologist.
would be:
“That is all right”, said the Psychologist.
Computer code should be enclosed with 「single corner bracket」. (Unicode 12300 12301)
Computer file path or name, should be enclosed with tortoise shell bracket, for example: 〔/Users/xah/Documents〕. (Unicode 12308 12309)
Text is never flushed on the right.
Person's names with abbreviation, such as Harold S. M. Coxeter, is written without the period. e.g. “Harold S M Coxeter”.
Sentences should always end in a period, or exclamation mark “!” or question mark “?”. In particular, the last symbol of a sentence should not be a quotation mark. In other words, quoted text is a special string demarcated by the matching curly quote glyphs, and the inclusion of a quoted text does not change the syntax of the text outside the quote. For example, like this: “Note the ending period outside the quote.”.
The period symbol “.” is predominantly used for the purpose of indicating the end of a sentence. Avoid using it for abbreviations. For the case of abbrevs, usually one can do without the period today and in fact increases clarity. I haven't fully thought out about some cases, such as “e.g.”, “i.e.” that i employ often. Ideally, in tech expositions, i'd avoid “e.g.” and “i.e.”, but i haven't really found a substitute to my satisfaction. Using them without the period “eg ie” is too in-your-face. “e.g.” can often be replaced by “For example”, but that is too verbose or conspicuous to be suitable for inline list. “i.e.” can usually be replaced by “That is”, but “That is” is a idiom, and i haven't found a simple logical rephrase for it.
Date format is always “yyyy-mm-dd” or “yyyy-mm”. This is ISO 8601, adopted in much of web tech today (e.g. Atom Webfeed)
Always use metric system for units. Sometimes, use scientific prefix system for money or other units of quantity. For example, “Google paid 1 million dollars to settle” would be “Google paid 1 mega USD to settle”.
The “k” for “kilo” always mean 1000, not 1024, even in computing context. Similar for M (mega) and other. When binary base is meant, use “kibi”, “mibi”, etc. (See: Computing: mega vs mibi, kilo vs kibi.)
Person's name in english always follows the order First Name Last Name , unless there's cultural or other special reasons.
Author listing order, if alphabetical, follows first name, in contrast to the convention of family name.
For person's titles, in general, drop all loaded titles such as “Dr”, “PhD”, “Professor”, “Mr”. Use plain name. If title is a required information, then explicitly indicate associated institution and rank within that organization. If i deem the person honorable, add appropriate honor with the name with respect to human history. For example, instead of “Professor Harold Coxeter”, write “Geometer Harold Coxeter”.
Reference or citation follows this format:
《book or article title》 (date) By Author, Affiliation. @ HYPERLINK.
If it is a reference to tech manual, usually it starts with the Chinese reference mark ※. (e.g. doc of perl, python, java, emacs, css, w3c.)
《double》 or 〈single〉 angle brackets are used for book or article titles, following Chinese Punctuation tradition. Note, it's not the French «double angle quotation mark» or ‹single›.
The date follows this format yyyy-mm-dd. Depending on context, the date is typically date of first publication, or last major update. But it might be first written, date of edition, date of recognization or others. The “Affiliation” is often the magazine or journal name, or the company or university the author works for.