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
Help is available.
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
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.