The Writing Style of Xah Lee
… my writing is razor blades in hot buns to grammarians, choking 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 my sites. 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, unusual constructs, esoteric jargons, figure of speech, etc are used sans qualms against the lettering establishment.
The style described here is for my personal interweb writings. It does not represent the style used for business or other public writing.
Wording Style, Diction, Spelling
Article “an” vs “a”
The article “an” is always written as “a”. (See: To An or Not to An.)
Pronoun “I” vs “i”
“I” is always written in lower case “i”, unless it is the first letter in a sentence. (See: On “I” versus “i”.)
Saxon Genitive: “James's car” vs “James' car”
Possesives done with “'s” are always done in that form, no exceptions. For example, “James's car”, not “James' car”.
Short Sentence Length
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. Also, freely add comma to break a sentence into clauses, unless, it is too weird. (note the comma before the word “unless”.)
In creative writing, sometimes make sentences as long as possible with such conjunctions. Make it flow.
Omitting Articles: {a, the}
Articles such as {a, the}, can be omitted when it does not change the sentence's meaning on casual reading.
In general, the meaning of a sentence should come from explicit expression, not from implicit indications in grammar (such as tense/aspect, number, case, etc.). (See: The Meddling of English Article with Meaning • The Meddling Of The English Plurality On Meaning.)
Active vs Passive Voice
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 is Passive Voice? What's Aggressive Voice?.)
Do Not Spell Out Numbers
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.
Use Logical Spelling Variant
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 typos, shorthand, sloppiness. Examples:
- “thru” for “through”
- “truely” for “truly”
- “lawer” for “lawyer”
- “themselfs” for “themselves”
- “wifes” for “wives”
- “advices” for plural of “advice”
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 to be diffused to the general public.
No “and” for Last Item in Sequence
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.
Sometimes, use a more aggressive logical form. e.g. “My favorite fruits are: {peach, banana, cherry}”. (See: On the Postposition of Conjunction in Penultimate Position of a Sequence • English Writing Style: Oxford Comma and Strippers.)
No “respectively” in Parallel Sequences
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.
Diction
In tech tutorial or math exposition, use the most basic words only (A vocabulary of ~1200 words (note: Basic English has 850 words). See: Politics and the English Language (George Orwell)).
Avoid Idioms in Tech Writing
When i have time, avoid any idiom, even fundamental ones, by rephrasing it so that the meaning can be understood by normal interpretation of the word sequence. This is done by using unambiguous constructs, and use words that do not have many meanings, and use logical style. Examples:
- “In a way” → “In some interpretation”, “In some perspective”, “In some aspects”.
- “By the way, …” → “Also, …” or “O! …” or “Not related above, …”.
- “It turns out, …” → “It is discovered that …”, “It can be proven that …”, “I realized …”.
- “pretty easy” → “relatively easy”, “easy”, “seems easy”.
- “as far as i can see” → “by my understanding”.
- “In other words” → “Expressed alternatively: …”, “Also, …”, “From another perspective, …”.
- “on the other hand” → “from the other perspective”.
- “I can't ‘quite’ tell …” → “Difficult to see/discern …”.
Note: it's very time consuming to write without basic idioms.
Use of Figure of Speech and Literary Devices
In creative writing 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 yet in a manner contrarian, 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.
Syntax, Punctuation, Formats
Hyphen, Dash
2 types of dash are used.
- The short one - (U+002d), is used for hyphenated words, e.g. “drop-dead”.
- The long one, written either as “--” or — (U+2014) is used only occasionally. It is used for quotation attribution -- Plato, or sudden conclusive remark — a dash to the heart! The em-dash should always have spaces around it.
Any other type of dash (en-dash, etc) are not used. Also, word is never cut into two by hyphen for justification purposes.
No Right Justification
The right edge of text shall never be aligned.
Apostrophe
The apostrophe symbol is always a straight one (U+0027), not curly one. For example, “I'm”, “Mary's”. (See: The Moronicities of Typography: Hyphen, Dash, Quotation Marks, Apostrophe.)
Symbol Used for the Quotation Mark
The symbol for quotation is always written using matched curly double quotes “like this”, and not "straight" quotes.
Punctuation Style in Quotation
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 in Wonderland: Chapter 1:
… , “and what is the use of a book,” thought Alice “without pictures or conversation?”
Note the comma inside the first quote. It should be:
… , “and what is the use of a book”, thought Alice, “without pictures or conversation?”.
Also note the added period at end of paragraph.
Another example from Time Machine: Chapter I:
“That is all right,” said the Psychologist.
should be:
“That is all right”, said the Psychologist.
Quoting Computer Code
Computer code should be enclosed with 「single corner bracket」. (U+300c, U+300d)
Computer file path or name, should be enclosed with tortoise shell bracket, for example: 〔/Users/xah/Documents〕. (U+3014, U+3015)
(these are often converted into HTML tags)
Punctuation in List Items
Bullet or list items, or items in a ordered list, are each considered independent clause, as elements of a set. It should never end in a comma or semicolon. They should all end with full stop sign, or all without any punctuation when items are short.
Period in Person's Names
Person's names with abbreviation is written without the period. e.g. “Harold S. M. Coxeter” is written as “Harold S M Coxeter”.
Sentences Should Always End in a Period
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 quotes, 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 used solely for the purpose of indicating the end of a sentence, as much as possible. 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 to impress a academic association. 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
Date format is always “yyyy-mm-dd” or “yyyy-mm”. This is ISO 8601 convention , adopted in much of web tech today (e.g. Atom Webfeed.)
Use Metric System
Always use metric system for units, sometimes even in contexts that's conventionally not done. (e.g. money) For example, “Google paid 1 million dollars to settle” would be “Google paid USD$1M to settle”. The “M” there is SI prefix “Mega”, and “USD” is ISO 4217 3-letter code for currency.
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, Title
Order of First Name, Last Name
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.
No Honorary Title
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”.
Citation Format
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. 〔see Intro to Chinese Punctuation〕 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 wide awareness, or others. The “Affiliation” is often the magazine or journal name, or the company or university the author works for.