Here are typographical, spelling and lexical conventions for the content of this site.
They apply to
- Markdown source files for code.kx.com, hosted at KxSystems/docs
- Technical White papers prepared for code.kx.com
Contributions to the series of Kx Technical White Papers should be drafted in Markdown and follow the conventions in this guide. Image files should be ≤500px wide.
Use the source files for published papers as models:
The conventions have two objects.
The first is essential to the working of the site’s custom search engine.
The site’s build script compiles an index.
To do this it parses the Markdown source files.
It is less tolerant than the MkDocs site generator.
For example, MkDocs recognizes
~~~ as a code fence, and the language suffix is optional.
Our indexing script does not.
It recognizes only backtick code fences, and requires language suffixes to them.
The second object of these conventions is to remove ambiguity. In practice, they rarely do, because in most instances of potential ambiguity the author’s intent can be deduced by an intelligent reader.
They nonetheless sometimes have important work to do. For example:
For unary values the keyword
overis preferred over the iterator Over, e.g. for unary
f overrather than
The value of consistency
Consistent observation of the conventions relieves the reader of the cognitive load of resolving ambiguities, and raises the value of the documentation.
Writing is hard
Plain Words: A guide to the use of English by Sir Ernest Gowers
Politics and the English Language by George Orwell
It’s a nervous tic of analytical philosophy to be forever wishing to clarify distinctions that nobody is actually confused about.
— Jerry Fodor
Plain and simple
Don’t elegant and elaborate sentences in a formal style lend authority to what you say? Rarely. Prefer plain and simple style.
There were four interview rooms. Each was a windowless concrete cube divided exactly in half by a wall-to-wall desk-height counter with safety glass above. Caged lights burned on the ceiling above the counter. The counter was cast from concrete. The grain of the formwork lumber was still visible in it. The safety glass was thick and slightly green and was divided into three overlapping panes, to give two sideways listening slots. The centre pane had a cut-out slot at the bottom, for documents. Like a bank. Each half of the room had its own chair, and its own door. Perfectly symmetrical.
— Lee Child, 61 Hours
When saying what to do, write as you would speak – in the second-person imperative. Address your reader as you.
At this point the foo should be barred.
The user should take care to bar the foo.
Bar the foo.
An excellent example from a snake catcher in Australia.
Hoser warned that snakes could be dangerous, and not to deal with them without professional help.
“If you see a snake don’t go near it. Nine times out of 10 if they’re in your garden they’re passing through,” he said.
“If you get bitten, bandage on your arm, straight to hospital.
“Without treatment you’re likely to die. With treatment you probably won’t die.”
— The Guardian 2020.09.01
Despite all you do, much technical writing is necessarily repetitive and tedious. Occasional humor can lighten it, but a little goes a long way – a very long way.
Here are the most important – or most commonly neglected – rules.
- Use American spelling, e.g. customize not customise
- Use the revised terminology to describe the grammar of q
- Use sentence case for headings, with minimal punctuation and no final periods, e.g. Coding conventions for interfaces, not Coding Conventions for Interfaces.
- Use bold type for keywords to assist a visual search.
- Use italic type for
- to refer to a section by its heading, e.g. see Machine learning
- to denote a word rather than its meaning, e.g. “It can be difficult to search for words like like and and.”
- titles of books, journals, films and record albums (with sentence case), e.g. Q For Mortals
- Use double typographer’s quotes around
- reported speech, e.g. “Go away,” he said.
- titles of articles, essays, and scholarly papers
- Use single typographer’s quotes
- to denote possession (but never plurals), e.g. 1983’s hit “Oobop Shebam” was her best work in the 1980s, and perhaps the 1980s’ favorite song.
- to remove emphasis, i.e., when a word or phrase is not meant literally (sometimes called ‘scare quotes’)
- Use typewriter quotes only in code elements, e.g.
- Use spaced endashes for parenthetical phrases – such as this – not spaced hyphens and not emdashes, spaced or unspaced.
- Use numbered lists (or headings) only when there are multiple references to the numbers; otherwise use bulleted lists.
- In Markdown use backtick code fences to delimit code blocks, and label them with the corresponding language.
- Use Grammarly to proof your text before submitting it for review.