House Rules

Content

1. General

• Write in service of the objective.
• Minimum information necessary to explain the task or concept and satisfy requirements.
• Minimum changes to default settings and processes.
• Separation of instruction and discussion (especially when converting blog posts).

2. Informational and Instructional Paragraphs

• Refer to these sample paragraphs for the style our documents should strive to maintain.

3. Tutorial Structure Best Practices: Audience Awareness: Start with a simple method and progressively introduce more advanced techniques in subsequent tutorials.

Learning Objectives: Clearly define the learning objectives of your tutorial. If the goal is to introduce a concept, the simplest method may be sufficient. Different methods might be described in more advanced tutorials to show complexity or versatility.

Progressive Complexity: Structure your tutorials in a way that introduces complexity gradually. Begin with the basics and build upon them, providing additional methods as learners progress.

Ultimately, a combination of both approaches can be effective, especially in more comprehensive learning materials where simple methods lay the foundation and various methods offer deeper insights.

• Organize tutorials with the following structure. Note this is the recommended starting point, not a template. Add and remove sections as necessary.
  • Introduction
  • Installation
    • Prerequisites
    • Installation Steps
  • Application Details
  • Resources
    • Source Code
  • Next Steps
• Example: Entando Customer Portal structure

Tone

1. Pronouns

• Use “you” as needed, particularly for tutorials, to refer to the reader/user.
• “We” can be used to refer to Entando as a company or application.
• Do not mix “we” and “you” when writing tutorials.

Page Components

1. Lists

• General Guidelines:
  • Use lists for complex information with multiple attributes, e.g., within introductions.
  • Use periods as needed but attempt to keep it uniform throughout a list.
  • Capitalize the first word.
• Instructions/Numbered Lists:
  • Steps should not include lengthy descriptions, just pointed instructions.
  • Instructions should always be numbered if there is more than one in a section or under a header.
  • Numbered instructions followed by commands or code change should end with a colon stop.
  • For better readability, if a list or a set of instructions has more than 3 items, they should be numbered or include letters to organize them. i.e., A, B, C, for a list of subheadings or types
• Bulleted lists:
  • Bullets should be concise for ease of scanning.
• Indentation:
  • Effective in confining supplemental information to a line item.

2. Bolds, Italics, & Backticks

• Bold Text:
  • Limit use to easily scan a page for terms/instructions.
  • Use sparingly; save this styling element for key thoughts, takeaways, questions.
  • Use in lieu of a header to better organize a page or draw attention to a section (e.g., Step 1).
• Italics:
  • Minimize use; acceptable to accurately represent source material, e.g., when referencing an italicized page element.
• Backticks:
  • Use to identify commands/code outside of code blocks.
  • Backtick page elements, navigation, files, directories and paths referenced within instructions to highlight name or location (ease of reading, processing steps to follow).
  • Do not backtick files, directories or paths referenced outside of pointed instructions (clutters page and detracts from / interrupts content).

3. Links

• Use links to explain related concepts or tools, instead of digressing from product information.
• Do not overuse external links because they will often change, leading to "link rot." Periodically check that external sites are maintained.
• Internal links should always be relative links.
• Never link to source code READMEs for instructions. Instead, restate source code information explicitly.

4. Placeholders, field names, variable names

• All variable names should be meaningful, clear and accurate.
• Field text should be signified with double quotes.
• Placeholder text denoting user-specific substitutions should be capitalized, begin with "YOUR" and use hyphens to separate words, e.g., YOUR-INGRESS-IP.

5. Images

• Images should be included as needed to illustrate a concept or instruction.
• Image content should be limited to essential visual elements:
  • Images should be confined to the portion of a UI or component under discussion, such as an MFE graphic or menu.
  • Page headers and extraneous elements should be omitted to alleviate the burden of image maintenance necessitated by updates.
• Recommended tools:
  • Preview (Mac)
• Scaling and compression:
  • Use scaling to compress images via pixel interpolation. Recommended targets are 72 pixels per inch and a width of 10-14 inches.
  • Adjust Image Size to a maximum of 14 inches width.
  • To avoid noticeable latency in rendering, images should not exceed 100kb. Compress images via www.tinypng.com to reduce file size while maintaining quality.
  • Allow Vuepress and CSS configurations to control default image dimensions. If necessary, hardcode either the height or width parameter to force image scaling. To avoid skewing proportions, do not hardcode both the height and width.

Conventions

1. Acronyms and Initialisms

• Note that an acronym abbreviates a term or phrase into an actual word while an initialism abbreviates a term or phrase into a string of letters that do not correspond to a word.
• Explicitly define immediately following first use of term, e.g., micro frontend (MFE).
• Do not include if the term will not be repeated 3x or more on the same page.

2. Common Formats

• Refer to this list to ensure that terms are formatted appropriately and consistently.
• Refer to Entando's Glossary for a complete list of terms related to our product.

3. Capitalizations

• Capitalize a singular noun when “Entando” precedes it to indicate a proprietary entity (e.g. Entando Application).
• Capitalize a plural noun only when “Entando” precedes it (e.g., Entando Bundles); plurality presumes generalization and does not refer to a specific instance.
• Capitalize Entando components that have been customized. Do not capitalize general references.