OrderEZ developer documentation style guide

This style guide provides an overview of editorial guidelines for writing clear and consistent OrderEZ-related developer documentation.

If this style guide doesn’t answer your question, you can simply try and match the writing style from one of the project specification documents (opens new window) or OrderEZ Help Center (opens new window).

For further writing style considerations, use the following references:

Type of question	Reference
Spelling	Follow Merriam-Webster.com (opens new window)
Non-technical style	Follow The Chicago Manual of Style, 17th edition (opens new window)
Technical style	See the Microsoft Writing Style Guide (opens new window). But consider whether Microsoft's guidance applies; some of it might apply only to Microsoft products and interfaces.
General style guide	Follow Google developer documentation style guide (opens new window)

Principles

This is a set of principles this documentation should continue to live (and grow) by.

Participatory

The documentation writing process should include everyone from developers to testers.

Everyone is welcome to join the writing process, but it is an integral step of the development process for the whole development team.

Skimmable

Structure content to help readers identify and skip over concepts that they already understand or see are not relevant to their immediate questions.

Save your readers’ time by writing like a newspaper instead of a novel.

Specifically:

• Headings — should be descriptive and concise.
• Hyperlinks — should surround words that describe the link itself (and never phrases like “click here” or “this page”).
• Paragraphs and list items — should begin with identifiable concepts as early as possible.

ARID

Accept (some) Repetition In Documentation.

Documentation is not a code, therefore some amount of business logic will need to be described again in multiple places. Where possible, try to use hyperlinks in content in order to avoid describing the same logic.

Exemplary

Include (some) examples in the content.

Try to write examples for the most common use cases, but not for everything.

Consistent

Use consistent language and formatting in content.

Current

Incorrect documentation is worse than missing documentation.

When software changes faster than its documentation, the users suffer. Keep it up to date. Every production server update should be followed by a documentation update.

Addressable

Provide addresses to readers which link directly to content at a granular level.

Cumulative

Content should be ordered to cover prerequisite concepts first.

Don’t run in front of the cart thill (don’t jump the gun) by describing a specific feature if more general ones aren’t included yet. (ex. don’t start documenting product tier pricing, if products haven’t been described yet)

Complete

Within each publication, cover concepts in full, or not at all.

When the documentation reaches the point where it makes sense to complement every production update with a documentation update, try to cover all of the features included in the changelog or none at all.

Beautiful

Visual style should be intentional and aesthetically pleasing like with any other Neopix product.

Text formatting

Bold

• Use bold formatting (**) for UI elements. (Click on Accept order button)
• Use bold formatting for important notices. (Note: something very important to draw the reader’s attention to it)

Italic

• To indicate emphasis in Markdown, use single asterisks (*)
• When you need to draw attention to a particular word or phrase in the prose of your documentation, such as when introducing a key concept or new word, or when discussing a particular word. (Scheduled order types are now created by outlets as pending orders with a requested delivery date. instead of Scheduled order types are now created by outlets as pending orders with a requested delivery date.)
• Italicize titles and headings, unless they're part of a link. (as explained in Integrations section)

Underline

• Unless it’s linked text, do not underline.

Code font

• Use ` in Markdown to apply a code in text, inline code, and user input.
• Use code blocks, ```, for code samples or other blocks of code.
• Do not override or modify font styles inline

Commas

• Use Oxford comma: In a series of three or more items, use a comma before the final and or or. (Every single order has at least three elements at all times: order number, date requested, and delivery on date)

Quotation marks

• In English (US) the rule of thumb is that commas and periods always go inside the quotation marks, and colons and semicolons (dashes as well) go outside. ****(See the section titled “Supplier create order flow.”)
• When a cross-reference is a link, don't put the link text in quotation marks. (See the section Supplier create order flow (opens new window))
• The only time to use single quotation marks in our documentation is when nesting a quotation inside another quotation.

Headings and titles

• Use heading tags to structure your content hierarchically ( #, ##, ### )
  • Don't skip levels of the heading hierarchy. For example, put a ### tag only under a ## tag.
  • Don't use empty headings or headings with no associated content. (#Orders#; ##Order History##). Give some introduction at least after higher level title before moving on to the lower level.
• When possible, avoid using -ing verb forms as the first word in any heading or title. (Supplier create order flow instead of Supplier creating order flow)
• Don't include numbers in headings to indicate a sequence of sections.
• When using an abbreviation in a heading or title, spell out the abbreviation in the first paragraph that follows the heading or title.
• Don't put a link in a heading because it can easily be confused as a style applied to a heading instead of a link.

Tone and content

• Be conversational and friendly without being frivolous - In your documents, aim for a voice and tone that's conversational, friendly, and respectful without being overly colloquial or frivolous; a voice that's casual and natural and approachable, not pedantic or pushy. Try to sound like a knowledgeable friend who understands what the developer wants to do.
• Don't pre-announce anything in the documentation - Avoid trying to document future features or products, even in innocuous ways.
• Use descriptive link text - To write link text, use descriptive phrases that provide context for the material that you're linking to.
• Use the gender-neutral singular pronouns they, their, and theirs whenever possible, and avoid specifying gender.
• Avoid where possible:
  • Buzzwords or technical jargon.
  • Placeholder phrases like please note and at this time.
  • Choppy or long-winded sentences.
  • Starting all sentences with the same phrase.
  • Current pop-culture references (evergreen ones are, however, welcome)
  • Exclamation marks, except in rare really exciting moments.
  • Internet slang and abbreviations
  • Jokes at the expense of customers, competitors, or anyone else.
  • [finding new examples to add to this list]

Language and grammar

Capitalization

• Follow the official capitalization for the names of brands, companies, software, products, services, features, and terms defined by companies and open source communities. (Xero, Shopify Store, etc).
• Don't use unnecessary capitalization.
• Don't use all-uppercase, except in the following contexts: in official names, in abbreviations that are always written in all-caps, or when referring to code that uses all-caps.
• Don't use camel case (opens new window), except when referring to code that uses camel case. (If the product has pricingUnit, it is displayed here)
• In documentation titles and headings, use sentence cases. That is, capitalize only the first word in the title, the first word in a subheading after a colon, and any proper nouns or other terms that are always capitalized a certain way. Don’t put a period at the end of a title or heading.
• In references to any title or heading from a document that follows this guide, use sentence case even if the title or heading itself uses title case (most probably a case with product specification documents). That way, when the title or heading is eventually updated to a sentence case, the reference will match.
• If not sure how to capitalize a title properly, for reference visit https://capitalizemytitle.com/ (opens new window)
• Use sentence case for image and table captions. Use sentence case for labels, callouts, and other text in images and diagrams.
• Use sentence case for all the elements in a table: contents, headings, labels, and captions.

Active voice

• In general, use active voice instead of passive voice, although there are exceptions. (Click on the confirm button and the server sends an email instead of When confirm button is clicked, the order email is sent by the server)
• In certain cases, it's okay to use passive voice:
  • To emphasize an object over an action. (The PDF file is downloaded)
  • To de-emphasize a subject or actor. (If the error is thrown instead of If you create an error*)*
  • If readers don't need to know who's responsible for the action. (The database is backed up every month)

Abbreviations

• Don't create your own abbreviations (Delivery fee instead of DF)
• Use recognizable and industry-standard acronyms and initialisms. If the reader has to think about an abbreviation, it can slow down their reading comprehension.
• Don't use internet slang abbreviations such as tl;dr, ymmv, RTFM, or others. Write out what you mean in a non-figurative way.
• Prefer English terms over Latin abbreviations. Don't use i.e. or e.g.; instead, use that is or for example