Style guide

Here are typographical, spelling and lexical conventions for the content of this site.

Scope

They apply to

  • Markdown source files for code.kx.com, hosted at KxSystems/docs
  • Technical Whitepapers prepared as PDFs for code.kx.com

Purpose

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

The conventions are nonethless valuable, because occasionally they have important work to do. For example:

The adverb over (/) is to be preferred over the operator over.

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.

Summary

Here are the most important – or the 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 italic type for emphasis and bold type for keywords to assist a visual search.
  • 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 code fences to delimit code blocks, and label them with the corresponding language, e.g. ```q.
  • Use Grammarly to proof your text before submitting it for review.

References