Default Article Template

FreshDesk Templates

Snagit Screenshots

Boxes

Callouts 

Arrows

Highlighting

Shortcuts

Alt Tags

Miscellaneous

Text Formatting

Table Formatting

Writing Guidelines 

Icon and Button References

Page Element References

Article Title

Multi-state Documentation

Additional Guidelines for Improving Readability


Default Article Template

The Default Article Template is automatically loaded when you create a new article.


Rename Article Template to the appropriate article title.
NOTE: See the Article Title section in the Writing Standards section below.



Table of Contents (TOC)

Place cursor where the TOC should be inserted, and click TOC.


Typically the TOC should be inserted after the article is written.

Once inserted, format the TOC to look like this:
(Not every article will have every heading.)


Default TOC settings need to be updated, including:

  • Remove "Table of Contents" heading.
  • Remove Up arrows from TOC.
  • Remove bullets.
  • Increase font size to 14.
  • Do not include "Table of Contents" in the TOC.
  • Only include top-level (H2) headings; remove secondary (H3) headings.
  • Note that the article headings should have Up arrows. However, the first heading (closest to the top of the article, usually Overview) does not need the Up arrow.


Overview

  • Omit the navigation screenshot.
  • Format breadcrumb navigation with the Greater Than symbol, preceded by "Navigate to."
  • Bold the breadcrumb.
  • Brief description: See Documentation Standards "Additional Guidelines for Improving Readability" for tips on writing the description. 
  • Include a screenshot of the full page. (Smaller sections can be included elsewhere.)


Security

  • Follow a standard format.


Configurations and Tables


  • Under Configurations, include all applicable information needed for setting up and using the feature, such as:
    • Enabling the feature
    • District and school options
    • Code setup
    • Translations
    • Other prerequisites
  • Under Tables, include table information when needed.
    • List all tables related to the feature (name and three-character code)
    • List all fields applicable to the feature (name and code)


Options

  • Describe all options and fields on the page.
  • Include screenshots when helpful.
  • 'Options' may be renamed to 'Steps' if appropriate.


FreshDesk Templates ↑

The following templates are loaded in Knowledge base (Aeries Software) > Templates:

  • *Article Template Default - The standard template for most FreshDesk articles. When you create a new article, this template is loaded by default. For FAQ articles, use the FAQ - Formatted template.
  • Documentation Standards - This document. Do not use as a template.
  • Example Header w/Arrow - Allows you to include an H2 header preformatted with with an Up arrow. Use for longer articles that have a TOC at the top.
  • Advanced Section Filter Text Blurb - Allows you to include a standard statement related to schools using Master Schedule. Use in very specific cases.
  • Yellow Note - Allows you to insert a preformatted yellow box that can be used to highlight important notes in the article. 
  • FAQ - Formatted - The template to use for FAQ-style FreshDesk articles.
  • Chart Template w/TOC - Allows you to include a preformatted table with a TOC. 
  • Chart w/Alternate Shaded Rows - Allows you to included a preformatted table with every other row shaded gray. Use for longer tables.


Add a template to any FreshDesk article by using the Quick Insert feature. 

Note that the template title is not inserted.

Templates can only be added to articles; they cannot be inserted into another template. 


  1. From a blank row within a FreshDesk article, click the Plus icon.
  2. Click the Insert template icon.
  3. Select the template, then click Insert template.
    Yellow Note Template



Snagit Screenshots ↑


Always obscure any personally identifiable information (PII).


Apply a border in FreshDesk.




Boxes

Used to draw attention to a particular section of a page.

  • Yellow-Orange: For general use
  • Red: For warnings only



Box Settings
  • Fill = transparent
  • Outline
    • Yellow-Orange #F7AC08
    • Red #F20909
  • Shape = rounded corners (more square, less oval)
  • No shadow
  • Thickness = 4
  • Opacity = 100%



Callouts 

Used to add text to a screenshot.

  • Yellow-Orange: For general use
  • Red: For warnings only




Callout Settings
  • Fill color  
    • Light Orange #FDF3DC
    • Light Red #F7DEDE
  • Outline and Arrow color
    • Yellow-Orange #F7AC08
    • Red #F20909
  • Shape = rounded corners (more square, less oval)
  • No shadow
  • Outline Size = 4
  • Arrow Style = solid line, default arrow
  • Arrow Size = 4
  • Opacity = 100%
  • No shading
  • Font
    • Arial 
    • Black 
    • Padding = 0
    • Left justified if more than one row of text
    • Vertical alignment = centered



Arrows

Used to point to a specific place on the page.

  • Yellow-Orange: For general use
  • Red: For warnings only




Arrow Settings
  • Color
    • Yellow-Orange #F7AC08
    • Red #F20909
  • No shadow
  • Arrowhead and end styles = Curved
  • Solid line
  • Width = 3
  • Opacity = 100%
  • End Size = 5
  • Use Bezier Curve to avoid covering text.


Highlighting

Not used. 


Shortcuts

Use Quick Styles and My Colors and Favorites for easy access to the Aeries standards.

 



TO DO: Jen will create an Aeries theme for docs.


Alt Tags

Add alt tags for all images. Indicate when an image is specific to CA or TX.


Alt tags should follow guidelines for ADA accessibility. See Web Accessibility Tutorials - Informative Images for information.
Examples:

  • "Import Test Results page"
  • "Security page with Insert permission selected for ACT table"
  • "Match Options section with appropriate fields selected"


  1. Click the Code View icon.



  2. Locate the image tag, and add/update the alt tag to be descriptive.
    Include California or Texas in the description when it is specific to one or the other.


Miscellaneous

  • If a Snagit screenshot has any transparency, it cannot be pasted into FreshDesk. Crop or remove transparency before copy/pasting.
    One way to avoid transparency is to clear the Automatically expand the canvas to fit objects setting in the Snagit Editor Preferences.


Text Formatting ↑

AvoidBold
  • Underline
  • All caps (see exceptions)
  • Centered text
  • Quotation marks
  • Excessive (more than two) font colors 
  • Excess/distracting formatting in general
  • Aeries
  • Field and option names
  • Table names
  • Button names (not the word 'button)
  • Icon names (not the word 'icon')
  • Column headings
  • Section headings
  • Page titles 
  • Tab names
  • Breadcrumb paths
  • Aeries Gradebook
  • Teacher Portal, Student Portal, Parent Portal
Aeries Proper Nouns (Capitalized)All Caps
  • Fall Semester, Spring Semester, etc.
  • CALPADS Reporting
    e.g., CALPADS Fall Reporting
  • PEIMS/TSDS Submissions
    e.g., PEIMS Fall Submission
    e.g., PEIMS Submission 1
  • Attendance Reporting Period (Texas)
  • Aeries Gradebook
  • Teacher Portal, Student Portal, Parent Portal
  • District Assets 
  • Master Schedule
  • Teacher of Record
  • Features
    • Flex Scheduling
    • Online Enrollment
    • Staff ID-Based Counselors (include hyphen)

Limited use for emphasis, such as:

  • DO NOT
    e.g., DO NOT click Save until you have reviewed the data.
  • MUST
    e.g., You MUST obscure PII in all screenshots.
Miscellaneous 
  • Capitalize the word Report when it is part of a report title.
  • OneRoster 
  • Ed-Fi


Table Formatting ↑

For longer charts, use the templates.

Generally:

  • Main Header row shading #2C82C9 (blue)
  • Main Header row text: white, bold
  • Secondary Header row shading: #EFEFEF (light gray)
  • Secondary Header row text: black, bold
  • Default font size (13)
  • Top align all text, including header rows.
  • Left align all text, including header rows. 
  • Right align any numeric content with decimals.
  • Exception: Data of uniform length (e.g., all numbers are one digit) can be centered. Column heading should match alignment.

Example - Chart w/Alternate Shaded Rows:

Example - Chart with Secondary Heading:



Writing Guidelines  ↑



AvoidUse Instead
Keyboard keys
  • "Click..."
e.g., "Click Enter..." or "Click enter..."
  • "Press..."
  • All caps, no bold

e.g., "Press ENTER"

Buttons on Aeries pages
  • "Press..."

e.g., "Press Save" or "Save the changes"

  • "Click..."
  • Bold, match case to button text

e.g., "Click Save."

Unnecessary wordse.g., "Please" or "Be sure to..." or "Don't forget to..."
  • Omit
Positive/negative statements
  • Negative statements 

e.g., "This does not apply to..."

  • Positive statements

e.g., "This applies to..."

Contractions

e.g., "Don't"

  • Spell out

e.g., "Do not"

Tense
  • Future tense

e.g., "...will be displayed"

  • Present tense 

e.g., "...is displayed"

Oxford (serial) commae.g., “Feed the cats, dogs and lizards.”e.g., “Feed the cats, dogs, and lizards.”
Words requiring a direct object

e.g., “A message displays”

(See Microsoft Manual of Style p. 246)

e.g., “A message is displayed”
Columns and sections (grouped fields with a heading)

e.g., “Under the XXX column...”

e.g., "Under the XXX section...”

e.g.,  “In the XXX column” or

e.g.,  “In the XXX section” or

e.g.,  “Under XXX..."

Breadcrumb navigation
  • Burying path in paragraph, pipe symbol

e.g., "To access this page go to the Student Data menu and select Demographics."

e.g., "Student Data | Demographics"

  • Greater Than symbol, bold

e.g., "Navigate to Student Data > Demographics"

  • Include tab names in breadcrumb path.

e.g., "Navigate to Scheduling Process > Courses > Other"

Capitalization
  • Inconsistency with displayed content.
  • Camel case, except when referring to displayed content.
  • Match capitalization to field, button, column name as displayed.
  • Otherwise, always use standard capitalization.
  • Exception: certain features may be capitalized (e.g., Flex Scheduling). See the Aeries Proper Nouns list above.
Links to other documents
  • URL in hyperlink text
  • Excess text

e.g., "See https://docs.aeries.works/x/xYauB for information about writing standards."

  • Document name in hyperlink text
  • Concise text

e.g., "See Writing Standards."

  • Always include hyperlinks to associated data when applicable.
  • Links should open in new tab.
Notes
  • Inconsistent use, overuse
Check boxes

e.g., “Select the Delete check box to...”

e.g., “Click in the Delete check box to...”

e.g., “Deselect...“

e.g.,  “Select Delete to...”

e.g.,  “Clear Delete to...“

Redundant explanatione.g., “Click Save to save changes.”e.g., “Click Save.”
(unless there is something unusual about what saving does.)
Clause order for action phrase

e.g., “To add a row, click Add"

NOTE: It is OK to use this order if the step is optional.

e.g.,  “Click Add to add a row.”
Combining "Add" and "New" (redundant)e.g.,  "Click Add to add a new row."
e.g., "A new page was added..."		e.g., "Click Add to add a row."
e.g., "A page was added"
Possessivee.g., “The birth date of the student”e.g., “The student’s birth date”
Ordinal numbers
  • Superscript
e.g., 1st
  • Normal formatting or spell out
e.g., first or 1st

Disable any settings that automatically convert ordinal numbers to superscript.
Numbers

e.g., "fourth grade"

e.g., "first semester"

e.g., "first cycle"

  • Generally, spell out one through ten. 
  • After ten, use numeric (e.g., 11).
  • Exceptions: school-related numbers:
e.g., "4th grade"

e.g., "semester 1" or "Fall Semester"

e.g., "cycle 1"

Forward slash
  • Incorrect use

e.g., "date/time" or "date / time"

  • Use only for either/or. Otherwise, hyphenate.
  • Omit space before/after slash.

e.g., "To/From"

e.g., “date-time”

Hyphen
  • em-dash (–)
  • hyphen (-)


Disable any settings that automatically convert a hyphen to em-dash.
Icon and button references
  • Inconsistent use
Page elements
  • Inconsistent use
Quotation Marks
  • Designate field or button names

e.g., ... the "Name" field...

  • Bold

e.g., ... the Name field...


Other Word choices



  • "Click in..." / "Click on..."

e.g., "Click on the Save button." or "Click on Save."

  • "Click..."

e.g., "Click Save."

  • "Enter..." (if user will be typing)

e.g., “Enter the first name.”

  • "Type..."

e.g., “Type the first name.”

  • "Choose..." / "Pick..." / etc.
  • "Select..."
  • "Turn on/off..."
  • "Enable/Disable..."
  • "In order to..."
  • "To..."
  • "...is shown"
e.g., “A message is shown” 

  • "...is displayed or opens"

e.g., “A message is displayed” or “A window opens”

e.g., "Left hand side of the page"

e.g., Left side, top-left, bottom-right, etc.

  • Hyphenate if followed by noun

e.g., "in the top-right corner"

  • otherwise omit hyphen 

e.g., "... is located on the bottom right."

  • "Line"

e.g., "Click Add to add a line."

  • "Row"

e.g., "Click Add to add a row."

  • "May"

e.g., "A district administrator may adjust permission."

  • "Can"

e.g., "A district administrator can adjust permission."

  • "Toggle to..."
  • "Go to..."
  • "Screen" or "Form"
Exception: “screenshot” is OK
  • "Page"

e.g., “The system displays the students...” or "The page displays the students..."

e.g., “The students are displayed...“

  • "TEA"
  • "the TEA"
  • Incorrect abbreviation

EX, etc.

"e.g., "

"For example, ..."

When part of a new feature isn't finished yet, but we are shipping the other part:
  • "Under development"
  • "Not available at this time"
  • Etc.
  • "Coming soon"
  • "in the page"
  • "on the page"
  • "Workaround" or "Issue"
  • Language that does not suggest a problem in the software
  • Setup vs. Set up
  • Login/Logon vs. Log in/on.
  • Backup vs. Back up
  • Setup is a noun. Set up is a verb. 
  • Login is a noun. Log on is a verb.
  • Backup is a noun. Back up is a verb. 
Mobile App Terminology
Navigationnavigation bar, navigation menu, etc.Menu
Turn an option on/off
Switch
Tool for picking from a scrollable list of options
Selector
Pop-up window, warning message, note, etc.
Notification
ScreenPageScreen


Icon and Button References

  • Icon and button names should be capitalized and bold.
  • The words 'icon' and 'button' should not be capitalized or bold.
  • Avoid using the word 'button.' For example, "Click Save" rather than "Click the Save button."
  • When referring to the icon, use the word 'icon.' For example, "Click the Save icon."


Icon imageName
Save 

Undo or Cancel 

Delete 

Expand or Collapse
Show or Hide
Minimize  
Flag
Activated Flag 
Print 
Help 
Tables and Fields 
Table Overlay 
Alerts
Favorites

Lock
Edit
Search
Previous and Next 
Reports
Pages


The following are examples of buttons:


Page Element References

The following words and capitalization should be used to refer to various elements on an Aeries page:


page

tab

field

button

icon

section  (e.g., ("Expand/collapse the section..." when referring to accordion-style tabs, etc.)

Navigation Menu

Knowledge Base


Article Title

Strive for Aeries-wide consistency by limiting titles to specific phrasing styles.

In general:

  • Avoid phrasing the title as a question.
  • Use either noun phrases or verb phrases.
    • Noun phrase example: A/B Days Setup or Absence Codes Overview
    • Verb phrase example: Build a Block Schedule Calendar
  • For verb phrases, use (for example): "Build a ..." instead of "Building a..."
  • Certain related articles (Texas-specific pages, Flex Scheduling, etc.) should lead with consistent phrase and format. For related articles, use the leading phrase consistently, formatted as phrase-space-hyphen-space (e.g., Texas - Attendance Reconciliation).
    The following are currently related:
    • Texas-specific
    • Flex Scheduling

Multi-state Documentation ↑

Ensure all content is tagged correctly for California, Texas, or both.

https://aeries.atlassian.net/wiki/spaces/QC/pages/11479384952/Multi-State+Documentation


Additional Guidelines for Improving Readability ↑

  • People prefer to scan rather than read. Make page scannable. Keep things along left. (People scan down along left side, not center.)
  • Use short words, short sentences, short paragraphs, short articles.
  • Front load paragraphs (i.e., put the most important information in the first few words).
  • Minimize distractions (fonts, font attributes, having to look in multiple places).
  • Use high contrast between text and background.
  • Feynman technique: The Secret Algorithm Behind Learning

  • Microsoft Manual of Style, Chapter 1.

  • Use examples and action verbs to "tell the story."
  • Consider Fitt's Law: bigger targets are easier to hit (e.g., hyperlinks, buttons, etc.).
  • Use active voice when possible.
    Passive: Core samples were tested on site by field technicians.
    Active: Field technicians tested core samples on site.

  • Avoid unnecessary noun clusters. Use connectors in, of, for, about to separate ideas.
    Cluster: blood cholesterol maintenance control diet
    Correct: a diet to control and maintain cholesterol in blood

  • Avoid deletion of “who,” “which,” or “that” function if it is necessary.
    Ambiguous: The supervisor wanted the chemicals locked up in low-humidity storage.
    This could mean one of the following:
    The supervisor wanted the chemicals that were locked up in low-humidity storage. OR
    The supervisor wanted someone to lock up the chemicals in low-humidity storage.

  • Do not insert lengthy phrases between a subject and verb or verb and object.
    Difficult: The task force, on engineering grounds, on conservative grounds, and on economic grounds, approved all design detail.
    Revised: The task force approved the design details because they met engineering, conservation, and economic standards.
  • Organize ideas clearly.
    Unclear: If the insulation contains a formaldehyde derivative, and if the insulation comes in contact with the wall board, and if no polyethylene barrier is used, and if no ventilation is provided for the insulation, health hazards may result.
    Improved: Health hazards may result if the following conditions exist:
    • The insulation contains a formaldehyde derivative.
    • The insulation comes in contact with the wall board.
    • No polyethylene barrier separates insulation and wallboard.
    • No ventilation is provided for the insulation.
  • Use the positive rather than the negative statement.
    Negatives: The contradictory results did not nullify the findings of the satellite laboratory.
    Positive: The contradictory results agreed with the findings of the satellite laboratory.



For introductory paragraphs: