Mechanics¶
A misplaced capital can turn a concept into a control. A changed quotation mark can break a command. Settle the small choices so the reader can concentrate on the work.
Capitalization¶
Use sentence case for headings, titles and new interface text. Preserve the exact capitalization of existing labels and menu items when quoting them.
Capitalize product names. Capitalize a feature name when it is the displayed name: “the Kerning panel” identifies a panel; “kerning classes” describes a concept. Use wording or structure for emphasis rather than unexpected capitals.
Numbers and units¶
Use numerals for things the reader compares, counts or types: 4 masters, 60 instances, 3 axes, 12 pt. Recast a sentence that would begin with a numeral when practical; otherwise spell out the opening number.
Name the actual unit. Use “1000 upm” when units per em is intended; “1000 units” leaves the scale unresolved. Put a space between a number and a unit abbreviation, except before the degree and percent signs.
A large quantity may benefit from a familiar comparison in explanatory prose. Keep the original quantity and unit available, verify the comparison and use it only when it improves understanding. An approximate image must not replace an exact setting.
Check a comparison by translating it back into the original units. If that produces a different quantity or a stronger performance claim, revise the comparison before polishing its wording.
Dates and versions¶
Use ISO order for numeric dates: 2026-08-30. In English prose, a named month is clear too: 30 August 2026. Avoid dates such as 03/04/26 that change meaning across locales. Localized text follows its target convention.
Write versions as the product does: FontLab 8, TransType 5, FontLab 8.4.2. Include a full build number in a release note when the source supplies it and it identifies the change.
Lists¶
Use bullets for an unordered collection and numbers for steps or rankings. Give parallel items a parallel grammatical form. Start items in sentence case; add a period when the item is a complete sentence.
Let the relationship decide the shape. Two actions can need a numbered list. A long collection can remain useful if its items belong together; group it when the groups help the reader find something.
Keep connected explanation in paragraphs. Splitting a thought into bullets can hide the cause, qualification or turn that makes it worth reading. See structure and navigation.
Tables¶
Use a table when readers need to compare the same fields across several items. Give each column a header and keep rows consistent. Put a procedure beside the table rather than inside a cell.
Definitions¶
Begin with what the term denotes. Add its application, mechanism or use when that distinguishes it from a nearby concept. A definition should let the reader recognize the thing.
Keep glossary definitions within 100 words and link to longer explanations. A short definition needs no padding. Store research provenance with the term data; the published sentence should explain the term.
Interface elements¶
In technical site content, use highlight syntax: ==Apply== renders as Apply. Use italics in neutral release notes and overviews: Apply. In plain Markdown without highlight support, use bold: Apply. Preserve the label itself in every format.
Name the element by its actual role. A panel groups related controls and may float or dock. A pane is a region within a window or container; it need not be a tab. A dialog may be modal or modeless. Use property bar where that is the product's term. You select a tool and invoke a command.
Give the verified full menu path on first mention with spaced greater-than signs: File > Font Info. A sentence around the path can be graceful; the path must remain exact.
Keyboard shortcuts¶
Join keys pressed together with a plus sign: Cmd+Shift+E. Give the macOS form first and the Windows form in parentheses on first mention, unless the document serves one platform. Preserve the platform's modifier names.
Use the key names shown on the target keyboard, such as Esc, Tab and Enter. Distinguish Return from Enter or keypad keys from other keys when the operation does. Describe a sequence in words or with commas so it cannot be mistaken for a simultaneous combination.
Code, formats, and identifiers¶
Use inline code for machine-readable text and things the reader types: kern, GPOS, OS/2.sTypoAscender, import fontlab, .vfc, --verbose.
Use lowercase in generic extension examples: .vfc, .ufo, .otf, .woff2. Preserve literal filenames and required case. Format names take their conventional capitalization: OpenType, TrueType, UFO, WOFF2.
Keep OpenType tags exact. Feature tags include liga, smcp and kern; table tags include cmap, GPOS and OS/2. Rhythm is no reason to rename an identifier.
Links¶
Say where the link leads or what it does. Place it where the reader can use the destination. Keep required facts on the current page if leaving would interrupt the task.
Link to an explanation when a question arises, and to a next task when the current one ends. See task guidance.
Placeholders¶
Mark a missing fact precisely in a working draft:
[ADD VERIFIED METRIC]for an unsupported number.[CONFIRM LABEL]for an unchecked interface string.[CONFIRM DEFAULT]for an unchecked default.[VERIFY CLAIM]for a claim that still needs evidence.
Resolve the marker before publication. A plausible number is harder to notice than a visible gap, which is how it gets into print.
YAML front matter¶
Keep prose values intact when YAML punctuation could change their meaning. Quote a single-line value containing a colon followed by a space or a space followed by #. A colon within a URL does not have the same effect.
For a longer description, a folded block joins ordinary adjacent lines with spaces:
description: >-
How to write for FontLab and Vexy: guide, book, glossary, and skills.
Use when a draft needs a register, a term check, or a translation pass.
Preserve indentation. Quote literal text beginning with indicators such as * or &. Use a literal block (|) when line breaks must survive.
Check the parsed value as well as parsing success. A missing comment fragment or a changed value type can otherwise pass without complaint.