The Writing Style on XahLee.org

Perm url with updates: http://xahlee.org/Periodic_dosage_dir/bangu/xah_style.html

The Writing Style on XahLee.org

Xah Lee, 2010-04-18

... 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 trespassings. 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 of logic with respect to computer parsing and human readability for writings that are tech tutorial or expositions. For essay or literary writing contexts, in addition to that, unusual constructs, esoteric jargons, figure of speech, etc are used sans qualms against the writing establishment.

The article “an” is always written as “a”.

"I" is always written in lower case “i”, unless it is the first letter in a sentence.

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 sentence. 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.

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.

Spelling. In tech writing contexts, spelling should be the more logical variation. e.g. “color” instead of “colour”, “dialog” for “dialogue”, “programing” for “programming”, “criterions” for “criteria”, “polyhedrons” for “polyhedra”... In literary contexts, the choice depends on the desired effect.

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.

Diction. In tech tutorial or math exposition contexts, use the most basic words only (A vocabulary perhaps about just 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 does not have many meanings. Here are some example of standard idioms: “in a way”, “by the way”, “it turns out”, “as far as i can see”, “In other words”, “on the other hand”, “it's pretty easy to...”, “I can't quite tell...”. For example, “In a way” can be “In some interpretation”, “In some perspective”, “In some aspects”. “By the way, ...” can be “Also: ...” or “O! ...” or “Not related above, ...”. “It turns out, ...” can be “It is discovered that ...”. “pretty easy” can be “relatively easy”.

The symbol for quotation is always written using matched curly double quotes “like this”, and not straight quotes.

The apostrophe symbol is always a straight one (ASCII 39), not curly one. For example, “I'm”, “Mary's”.

Only two type of dash are used. The short one “-” (ASCII 45), is used for hyphenated words, e.g. “drop-dead”. The long one, written either as “--” or “—” (Unicode 8212) is used only occasionally. It is used for parenthetical thought — like this —, or 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, figure-dash, etc) are not used. Also, word is never cut into two by hyphen for justification purposes.

Ellipsis is used for trailing sentence. It is always written as 3 dots, like this: “...”, and without a space before, and always with a space after. For example: “Once upon a time... but that's too long to tell.”. Another example: “... but you can't!”.

Person's names with abbreviation, such as Harold S. M. Coxeter, is written without the period. e.g. “Harold S M Coxeter”.

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.

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 outsite the quote. For example, like this: “Note the ending period outside the quote.”.

The full stop 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 employe 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.

Write “thru” for “through”... (todo: more to be added here)

Date format is always yyyy-mm-dd. 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 as well. For example, 1 million dollars would be 1 mega USD.

Author listing order, if alphabetical, follows first name, in contrast to the convention of family name. This is based on philosophy of individualism and libertarianism.

For person's titles, in general, drop all loaded titles such as Dr, PhD, Professor, Rev. Use plain name. If necessary, 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”.

Citations. Reference or citation follows this format: “book or article title” (date), by Author, Affiliation. The date follows this format yyyy-mm-dd. The date is typically date of first publication. Sometimes, it is the date of latest major update of that work. The “Affiliation” is often the magazine or journal name, or the company or university the author works for.

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), etc, are employed at will so that when read by a English expert, it is of maximum clarity, fluidity, 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, 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 needed, the linguistic background required, the symbolic logic of discernment, the size of vocabulary, the 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 what their little circle is used 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.

Claimer: I know more about English literature, linguistics, than most who has a BS/AS degree in these. My general knowledge related to writing, in subjects of mathematical logic, mathematical linguistics (syntax, grammar, semantics), computer languages (lisp, Mathematica, bash, perl, python, java, xml, css), standard writing styles and guides (e.g. MLA, Strunk & White), languages (Chinese, English), English vocabulary, pragmatics, evolution of languages, poetry writing, social aspects of language (jargons, argots, slangs, formation, purpose, internet era), lexicology, morphology, artificial languages (lojban), philosophies of languages, writing systems, written symbols (e.g. as exhibited in Unicode), math notations and its history, music notations, Chinese romanization systems (Pinyin, Wade-Giles etc), Chinese input systems (sound, char struct, their design, demograph...), typography, typesetting systems (TeX/LaTeX), are greater than most who has a PhD degree specialized in a sub-branch of these.

If you are learning technical writing, i recommend: Simplified English.

Popular posts from this blog

11 Years of Writing About Emacs

does md5 creates more randomness?

Google Code shutting down, future of ErgoEmacs