Style guide

This style guide defines the writing rules for both Axxya documentation sites: the public Nutritionist Pro docs (public/docs) and this internal runbooks site (runbooks/docs). It covers voice, grammar, punctuation, and language conventions. For the structural Markdown conventions (frontmatter, code fences, links, admonitions), see the Markdown guide.

If a topic isn't covered here, refer to these references, in order of preference: the Merriam-Webster dictionary for spelling, the Microsoft Writing Style Guide for technical style, and the Google developer documentation style guide as a secondary technical reference. Make sure any suggestion you take from a vendor guide is not vendor-specific.

Audience and voice

• The public docs are written for nutrition professionals: dietitians, nutritionists, food manufacturers, and food service staff using Nutritionist Pro. The runbooks are written for Axxya developers and operators.
• The writing style is professional but not formal. Contractions are fine.
• Assume readers skim and use search. Write to be clear, concise, correct, and comprehensive, not to entertain.
• Address the reader as "you." Avoid third-person references such as "the user" when you are giving instructions; they sound formal and impersonal.

Page structure

• Break topics into sections so readers can find information quickly. Each page begins with an introduction or an overview before the first heading.
• Use an "Overview" section when the first section summarizes what the article covers. Use an "Introduction" section when the first section provides background on the feature before the details.
• Never follow a heading directly with another heading. Write at least a sentence of content under every heading.

Writing style

• Write in US English using short, simple, everyday words. Short words are friendlier, save space, and are easier to read quickly.
• Keep sentences short and avoid multiple sub-clauses. If a sentence runs past about three lines, split it.
• Use active voice (subject-verb-object). Write "Click the icon," not "the icon should be clicked." Write "You need to add the code," not "the code should be added."
• Use gender-neutral language. When referring to a user or client, use "they," "the user," or "the client." When referring to a specific person, use that person's pronouns.

References and links

• When referencing another page in the Axxya docs, use its title as the link text. For example: "For the repository layout, see the Documentation page."
• When referencing external documentation, name the documentation and briefly describe the linked article. For example: "See the AWS documentation for creating an account."
• Link text must describe the destination. Do not use "here" or "this" as link text.

Steps and instructions

• When a step has an outcome or a follow-on event, put it in the same step, not in the next one. For example: "Click Create. The details page of the new item appears."
• If you tell the reader to check something, tell them what to do when the check fails. For example: "Check that the upload succeeded. If it didn't, check the file format."
• Try to keep procedures to a maximum of ten steps. If a procedure is longer, break it up.

Usage

• Use one space after a period, and only between sentences. Do not add a trailing space at the end of a paragraph.
• Use the Oxford (serial) comma: "Outlook includes Mail, Calendar, People, and Tasks."
• Place closing quotation marks outside commas and periods, and inside other punctuation, unless the punctuation is part of the quoted material.
• Do not use em dashes or double hyphens as punctuation anywhere in this repo. Use commas, semicolons, or separate sentences instead.
• Do not use arrow characters (such as the right-arrow glyph). Use an angle bracket (>) instead, for example in navigation paths.
• Only use an ampersand (&) when it is part of a proper name. Write "operations and maintenance," not "operations & maintenance."
• Use a slash to show alternatives ("High/low setting") with no spaces around it. Do not use slashes to link words; write "operations and maintenance," not "operations/maintenance."
• Avoid Latin abbreviations where possible; write "for example" instead of "e.g." If one is required, punctuate it and follow it with a comma: "e.g.," and "i.e.,".
• Hyphenate compound modifiers before a noun when the phrase could confuse without one (lower-left corner, read-only memory), when one word is a participle (left-aligned text), or when the modifier is a number or letter plus a noun (two-sided arrow, y-axis value). Do not hyphenate adverbs ending in "-ly" (highly graphical interface) or common prefixes (gigabyte, not giga-byte).
• For number ranges in prose, use a preposition: "between 2015 and 2017" or "from the 19th to the 22nd."
• Capitalize specific position titles (Project Manager) but not disciplines or services (project management services).
• When a menu item includes an ellipsis, include the ellipsis in the first reference, for example "the More Options (...) button." After that, call it the More Options icon.

Product names and capitalization

Capitalize Axxya product and module names, and keep UI element names capitalized exactly as they appear in the product. Lowercase the same words when they are used as common nouns. For example, "the Menu creation module" is a product feature, but "create a menu for the client" uses the common noun. If you're unsure, ask whether the word names the feature or the thing the feature manages.

Words and phrases to avoid

Avoid unnecessarily formal words. Prefer the common equivalent:

Don't use	Use
as well as	also, too
like (for examples)	such as
halt	stop
has the ability to, have an opportunity	can
in conjunction with	with
it is recommended	we recommend
subsequent	next
terminate	end
utilize	use
he or she	they

Use inclusive alternatives:

Don't use	Use
blacklist, whitelist	deny list, allow list
guys	people
master	main or primary
slave	secondary

Common usage notes:

• "Real time" is a noun; "real-time" is only an adjective.
• "Third party" is a noun; "third-party" is only an adjective.
• Use "such as" for examples. Only use "like" to imply things are similar but not the same.
• You have a login to a system, but you log in to use the system. You log out of a system.
• Write "step-by-step" and "up-to-date" when they modify a noun.

Acronyms

The first time you use a term, write the full name followed by the acronym in brackets, for example "the Recommended Dietary Allowance (RDA)." Use the acronym for the rest of the page.

Numbers

• Spell out numbers under ten (one, two, three). Use numerals for 10 and above.
• When two numbers appear together, spell out one of them: "Ten 3-person teams."
• Spell out a number that starts a sentence: "Ten teams started the event."

Lists

• A list needs at least two points. One point is a sentence, not a list.
• Always introduce a list with a leading sentence that ends with a colon.
• Use numbered lists for steps and for counted sets ("There are three ways to log in:"). Number every item with its real number.
• Use bulleted lists for unordered items. A bulleted list appears at the end of a sentence, never in the middle of one.
• Do not use linking text or punctuation between list items (no "and" or commas at the ends of items).
• If the points are complete sentences, start each with a capital letter and end each with a period. For simple fragments, use lowercase items with a period after the last one.

Headings

• Write all headings in sentence case: only the first word and proper nouns are capitalized. This applies to frontmatter title and sidebar_label values, in-body headings, and _category_.json labels.
• Headings never end with punctuation.
• Whenever possible, start a task heading with a verb in the infinitive: "Create a new label," "Import a menu template."

UI and typography

• Bold all UI item names: buttons, pages, tabs, sections, and fields. For example: "Click Save."
• Bold user input ("Type WCF in the field") and key names ("Press Enter").
• Users type information in fields; they do not "enter information into" fields. Information displays on the screen and in fields.
• Format all code, directory paths, and filenames as code with backticks. This also keeps spellcheck quiet. See the Markdown guide.

Images and screenshots

• Use images sparingly. Screenshots go out of date as the product changes, so only add one when it genuinely helps the reader.
• Always write alt text. Make it brief but descriptive, and do not preface it with "This image shows." Do not reuse the same alt text for multiple images on a page.
• Crop to the relevant part of the screen. Avoid full-page and full-browser screenshots; they are barely legible and age quickly.
• Do not annotate images with arrows, red boxes, or drawings. The crop should make the subject obvious.
• Crop out transient UI such as "coming soon" or "new" badges, and anything marked internal or development.
• Blur or replace any sensitive or customer data before capturing. Use test data (for example, "Test User" and test@test.com), never real customer information.
• Name images and image folders in snake_case with short, descriptive names. Never name an image 1.png, and never put spaces in image file names or paths.
• Keep a page's images in a folder next to the page so they are easy to find.
• Use PNG for screenshots (target under 200 KB; compress with a tool such as TinyPNG) and GIF only for short clips (target under 1 MB).

Dates, times, and file sizes

Follow the Microsoft style guidelines for dates, times, and file sizes. For file sizes, use a space and the standard unit: 5 MB, 100 GB.

SEO and metadata

• The frontmatter title renders as the page H1, so the first in-body heading is an H2. Write the title with the words a reader would search for, and keep it under 150 characters.
• Keep the frontmatter description under 160 characters so search results don't truncate it.
• Page file names become URLs, so keep them short, unique, and dash-separated.
• Well-organized pages with descriptive headings are the core of on-page SEO. Write so the most important words appear in the title, description, and headings.

Related

• Markdown guide, the structural Markdown conventions for these sites.
• Skills writer, editor, and formatting in the repo's .claude/skills/ folder encode these rules for AI-assisted writing and review.