America Learns Knowledge Base Style Guide

Purpose

This style guide defines the editorial, formatting, and visual standards for all Knowledge Base articles in HubSpot.

Its goal is to ensure articles are clear, consistent, accessible, and easy to scan—regardless of author or topic.

---

1. Article Structure

1.1 Article Types & Intent

All Knowledge Base articles must have a primary intent. Authors should choose the article type before writing to ensure clarity, scannability, and consistent AI routing. There are four article types: Task-Based, 

Task-Based Articles

Purpose: Help the user complete a specific action or workflow.

Use when:

• • The user is trying to do something in the system

  • The outcome is a completed action or configuration

Characteristics:

• • Step-by-step numbered instructions

  • Action-oriented headings

  • Screenshots or walkthroughs are often appropriate

Common examples:

• • Creating a Timesheet Template

  • Assigning a Survey to Programs

  • Updating User Permissions
    
    

Conceptual / Explanatory Articles

Purpose: Help the user understand how something works before taking action.

Use when:

• • The user needs context, definitions, or system behavior explanations

  • The article answers “How does this work?” or “What is this?”

Characteristics:

• • Descriptive sections, not step-by-step

  • Uses diagrams, tables, or examples

  • May link to related task-based articles

Common examples:

• • How Finish Line Statuses Are Calculated

  • Understanding Time Zones in America Learns

  • How Survey Logic Evaluates Responses
    
    

Troubleshooting Articles

Purpose: Help the user resolve a specific problem or unexpected behavior.

Use when:

• • The user encounters an error, warning, or incorrect outcome

  • The article answers “Why isn’t this working?”

Characteristics:

• • Organized by symptoms or error messages

  • Includes causes and resolutions

  • May include verification steps

Common examples:

• • Why Hours Are Not Appearing in Reports

  • Troubleshooting Survey Submission Errors

  • Common Reasons a Timesheet Cannot Be Submitted
    
    

Reference Articles

Purpose: Provide factual, lookup-style information.

Use when:

• • The user needs precise definitions, limits, or mappings

  • The content is not instructional

Characteristics:

• • Tables, lists, or definitions

  • Minimal narrative text

  • Not intended to be read linearly

Common examples:

• • Timesheet Status Definitions

  • Survey Question Types and Limits

  • Export Field Definitions

Guidelines:

• • Each article should have one primary type

  • Avoid combining multiple intents in a single article

  • If an article becomes too complex, split it by intent and cross-link

1.2 Base Article Elements

Every Knowledge Base article includes the following: 

---

2. Titles & Headings

2.1 Article Titles

• Titles should be concise and task-oriented.
• Titles default to Capital case and bold, designated via HubSpot theme settings. 
• Use verb-led, action-oriented titles (typically written in gerund "-ing" form) to describe what the user is doing or learning.
• Avoid filler terms such as “Overview,” “Introduction,” or “About”
• Ampersands (&) are used in article titles and headings when they improve clarity or reduce length.

Examples:

• Creating a Timesheet Template
• Managing Time Zones
• Troubleshooting Report Errors
• Archiving Admins & Reporters

2.2 Heading Hierarchy

Use a consistent heading structure to support scanning and automatic Table of Contents generation.

Heading Level	Use Case
Heading 1	Article title (used once)
Heading 2	Article summary (Used once)
Heading 3	Primary sections
Heading 4	Sub-Sections within a section
Heading 5	Rare; only for complex nested content

 

Rules:

• Headings 1 & 2 are only used once. Heading 3 is used to break up body content.
• Do not skip heading levels (e.g., no Heading 4s without a Heading 3).
• Every article should include at least one Heading 3 - Primary Section Header.

2.3 Heading Style

• Use Title Case for all headings.  This adjust by default based on HubSpot Theme Settings.
• Ampersands (&) can be used to 
• Do not include punctuation at the end of headings.

---

3. Spacing & Layout

3.1 Section Separation

• Insert a horizontal divider between major sections (Heading 3).
• Do not insert horizontal dividers between subsections (Heading 4)
• Do not insert blank lines between a heading and the body text that follows.
• Spacing should not be added as a rule between content areas, but discernment is encouraged.
  
  If a section is crowded and spacing is helpful (e.g., between an image and content, or between separate content paragraphs) a space can be added. 

3.2 Paragraphs

• Keep paragraphs short (3-4 sentences max).
• Break up dense information into lists or sub-sections.
• Avoid walls of text.

---

4. Typography

4.1 Font, Size, & Color Standards (Platform Defaults)

Fonts, color, and sizing are determined in the global HubSpot Theme styles.

If custom styling is available, use the following standards. Otherwise, rely on platform defaults, listed below.

Element	Font	Size	Case	Transform Case	Color HEX
Body text	Lexend Deca	16	Regular	None	#18202a
Heading 1	Lexend Deca	36	Regular	Capitalize	#334660
Heading 2	n/a	n/a	n/a	n/a	n/a
Heading 3	Lexend Deca	24	Bold	Capitalize	#33475b
Heading 4	Lexend Deca	20	Bold	None	#347d88
Heading 5	Lexend Deca	17	Regular	None	#18202a
Heading 6	n/a	n/a	n/a	n/a	n/a
Links	Lexend Deca	16	Regular	None	#347d88 with #f96d34 as hover font
Web Primary	Lexend Deca	n/a	Regular	n/a	#000000
Web Secondary	Lexend Deca	n/a	Regular	n/a	#000000

Rules:

• Body text should always meet accessibility contrast standards.
• Links must be visually distinct from body text.
• Do not rely on color alone to convey meaning.

---

5. Emphasis & Text Styling

5.1 Bold

Use bold to:

• Highlight key terms or interface labels
• Call attention to important warnings or outcomes
• Separate small sections within a paragraph (e.g., see Rules: above)

5.2 Italics

• Avoid italics unless required for product names or external standards.

5.3 Underlining

• Do not underline text unless it is a hyperlink.

---

6. Lists & Tables

Lists and tables are used to improve scannability and comprehension. Use them intentionally and consistently to support clear writing.

6.1 Numbered Lists

Use numbered lists for:

• Step-by-step instructions

• Sequential or time-based processes

• Tasks that must be completed in order

• A set number of items that are each referenced or expanded upon

Guidelines:

• Start each step with a clear action verb.

• Keep each step concise and focused on a single action.

• Use sentence case.

• Avoid combining multiple actions into one step.

• Follow a step with a screenshot or short clarification when helpful.

Screenshot Placement Rule (Numbered Lists)

Screenshots should be included selectively, not after every step.

Include a screenshot when a step:

• • Introduces a new screen, page, or modal

  • Requires locating a non-obvious UI element

  • Involves multiple fields, options, or configuration choices

  • Is commonly misconfigured or error-prone

Do not include screenshots when a step:

• • Involves a single, obvious action (e.g., click Save)

  • Repeats an action already shown earlier in the article

  • Adds visual clutter without improving clarity

Placement Guidelines:

• • Place screenshots immediately after the step they support

  • Do not interrupt a numbered list with multiple images per step

  • If many screenshots are required, consider using a walkthrough instead

6.2 Nested Lists

Use nested lists only when a step requires clearly grouped sub-actions.

Guidelines:

• Use lowercase letters (a, b, c) for nested steps.

• Limit nesting to one level deep whenever possible.

• Ensure nested items are dependent on the parent step.

• Avoid nesting if the steps can be rewritten more clearly as a flat list.

6.3 Bulleted Lists

Use bulleted lists for non-sequential information, including:

• Requirements or prerequisites

• Options or feature descriptions

Guidelines:

• Do not imply order or priority.

• Keep bullets short (phrases or single sentences).

• Avoid full paragraphs inside bullets.

• Use sentence case.

• Avoid overuse of nested bullets. 

6.4 Tables

Use tables to present structured, comparable information.

Table Usage Guidelines:

• Keep tables simple and readable.

• Use clear column headers.

• Avoid tables for layout or long-form explanations.

• Do not embed images or links excessively within tables.

• Ensure tables can be understood without the surrounding context.

 

Visual Table Guidelines:

Table building in HubSpot is admittedly finicky. Here are guidelines for consistency: 

• Cell height should be consistent across rows (e.g. 40pt row height), with the exeception of rows containing multiple lines of text

• Outer border: 1px, solid

• Inner borders: 1px, dashed

• Header row: Bold text with a cell background of light gray (HEX: #eeeeee)

• Column widths likely will require manual adjustment:

  • Use Table → Table sizing to adjust overall width

  • Use Style → Column width for individual columns

• Center-align cell content vertically.

Table Building Video Guide:

---

7. Callouts

Use callouts to draw attention to supplemental information without interrupting the main instructional flow.

7.1 Callout Options

There are four callout types with corresponding colors: 

• Notes: Use for neutral clarifications or additional information that helps explain the behavior of a feature.

  • Informational only

  • No action required

  • No risk implied

• Tips or Examples: Use for important context, best practices, or examples that help users work more effectively.

• • Includes examples, shortcuts, or recommended approaches

  • Enhances understanding but is not required to complete the task

• Cautions: Use for common mistakes or frequent misconfigurations that may cause issues or require rework.

• • Highlights “easy-to-get-wrong” steps

  • Signals potential frustration or unintended outcomes

  • Use for internal configuration risks, not external (e.g. AmeriCorps, Library Literacy, grant compliance risks)

• Warnings: Use for external compliance, policy, or regulatory risks.

• • Includes legal, contractual, or oversight implications

  • Common examples: AmeriCorps OIG policy, data retention requirements

  • Should be used sparingly and intentionally

7.2 Usage Guidelines

• Place callouts immediately after the content they relate to.

• Keep callouts brief, specific, and relevant.

• Do not use callouts for standard instructions or core steps.

• Do not mix callout types within a single message.

7.3 Formatting Callouts

All callouts must follow this format: CALL OUT TYPE (Optional Context): Text of the callout.

• Callout type must be in ALL CAPS

• Optional context appears in parentheses

• Follow with a colon

• Entire lead-in must be bolded

• Callout text follows in sentence case

Examples:

• NOTE (Accessibility): Screen readers may announce symbols differently.

• WARNING (AmeriCorps Compliance): Programs must retain records for seven years.

• TIP: Best practice guidance.

• EXAMPLE: Use role-based permissions to limit access.

---

8. Language & Tone

The language and tone of Knowledge Base articles should prioritize clarity, accessibility, and usability for a wide range of users, including those using screen readers, mobile devices, assistive technologies, or AI-supported help tools.

Articles should be easy to understand when read quickly, under stress, or without visual context.

To support this goal, articles should be written in plain language, targeting a reading comprehension level no higher than 9th grade. Clear, direct language reduces cognitive load, improves comprehension, and ensures guidance remains usable across different abilities, devices, and layouts.

8.1 Tone

Article tone should be:

• Clear, professional, and conversational

• Instructive without being patronizing

• Confident and supportive

This tone builds trust, helps users feel capable, and reduces friction when completing tasks—especially in high-stakes or compliance-related workflows.

8.2 Voice (Accessibility-First)

Knowledge Base articles must use a voice that remains clear and usable regardless of how the content is consumed (visually, audibly, or through AI tools).

Use second person (“you”) whenever possible.
Direct address keeps instructions clear and action-oriented.

Use active voice.
Active voice improves comprehension and makes instructions easier to follow.

Name the thing before describing its location.
Always identify the UI element, page, or action explicitly in text. Directional language may be used, but only as supporting context.

• Preferred:
  “In Mission Control, click Timesheets on the left.”

• Avoid:
  “On the left, in your Mission Control, click Timesheets.”

This ensures instructions remain understandable for screen readers, responsive layouts, and users who cannot rely on spatial orientation.

Directional language is supportive, not primary.
Left/right, above/below cues may be included, but must never be the sole way a user identifies what to click or where to go.

Use concrete, consistent action verbs.
Prefer simple verbs such as: Click, Select, Enter, Open, Save.
Avoid informal or ambiguous phrasing such as “tap into,” “navigate over,” or “hit.”

Consistency improves accessibility, scannability, and AI interpretation.

Limit each instruction to one clear action.
Single-action sentences reduce confusion and make instructions easier to follow when read aloud or skimmed.

Avoid assumptions about what the user sees.
Do not rely on phrases like “you should see,” “as shown above,” or “on this screen.”
Instructions should still make sense if images are removed or rearranged.

Write instructions that work without images.
Images and walkthroughs should reinforce written guidance, not replace it. Text alone should be sufficient to complete the task.

These voice rules ensure articles remain usable across devices, abilities, and future interface changes.

8.3 Terminology Standards

To maintain clarity and consistency across diverse programs, all Knowledge Base articles must use approved generic terminology wherever possible.

Approved generic terms are defined in the Approved Terminology Dictionary [LINK TO BE ADDED] and are used to ensure consistency across articles, AI responses, and client programs.

Consistent terminology reduces confusion, improves search accuracy, and ensures AI tools deliver reliable guidance.

Terminology Governance

When a needed term is not yet approved:

• • Use the closest approved generic term available.

  • Do not invent new terminology within an article.

  • Flag the term for review and potential inclusion in the Approved Terminology Dictionary.

When a client-specific term conflicts with generic language:

• • Always use the approved generic term for primary explanations and instructions.

  • Client-specific terminology may appear only:

    • In examples

    • In callouts

    • In clarifying parentheses on first reference

  • Client-specific terms must never replace or override core system terminology.

General rules:

• • Use one term consistently throughout an article.

  • Avoid synonyms for the same concept.

  • Do not alternate between generic and client-specific terms in instructions.

Reference: Approved Terminology Dictionary
All approved terms, mappings, and usage guidance are maintained in the Approved Terminology Dictionary [LINK TO BE ADDED]. Authors should consult this document before writing or revising articles and request updates when new terminology is required.

8.4 What Not To Do

To keep Knowledge Base articles clear, trustworthy, and user-focused, avoid the following:

• Do not use marketing language.

  Knowledge Base articles are instructional, not promotional. Avoid slogans, value statements, or persuasive framing.

• Do not use emojis or decorative symbols.

  Emojis and icons may not render consistently for screen readers, translations, or AI systems and should not be relied on to convey meaning.

• Do not reference internal systems or tickets.

  Avoid internal terminology such as JIRA ticket numbers, sprint names, support tools, or internal workflows.

  Exclusion: For our Impact-o-Pedia, we can, of course refrence these items. 

• Do not include release notes or change logs.

  Knowledge Base articles should describe current behavior only. Historical changes, feature launches, and version notes should live in release communications, not support documentation.
  
  Exclusion: For our Impact-o-Pedia, we can, of course refrence these items. 

These rules help keep articles timeless, accessible, and focused on user needs.

---

9. Images & Visuals

9.1 When to Use Images

• To demonstrate a workflow or UI interaction
• To clarify complex steps
• To reduce cognitive load

Avoid decorative images.

9.2 Image Standards

Image Element Standards:

Element	Standard
Tool	Snagit
Annotiation Color	America Learns color defaults within Snagit (#E74D61)
Shadow	23-point right-bottom drop

 

Image Insertion Guidelines:

• Center images in the middle of the article
• Place images immediately after the related step or paragraph.
• Use annotations sparingly, and not to replace information in the article. 
• Ensure text in images is legible.
• Alt text must be provided for each image. 

Snagit Setup:

9.3 File Naming vs. Alt Text (Simple Explanation)

File Naming Convention

Who it’s for:

• • Authors

  • Content managers

  • Future maintainers

  • File systems & automation

What it does:

• • Helps humans organize and find images

  • Helps with versioning and replacements

  • Supports migrations and automation

Example:
timesheets-create-template-settings-2025-03.png

File names are not reliably read by screen readers and should never be the only description of an image.

Alt Text

Who it’s for:

• • Screen reader users

  • Accessibility tools

  • AI systems that parse content meaning

What it does:

• • Describes what the image shows and why it matters

  • Conveys meaning if the image can’t be seen

Example:
“Timesheet Template settings screen showing the Template Length and Daily Goal fields.”

Alt text should describe purpose, not just appearance.

---

10. Links & References

10.1 External Links

• Open external links in a new tab.
• Use descriptive link text (avoid "click here").

10.2 Internal Links

• Link to related Knowledge Base articles when helpful.
• Avoid excessive cross-linking.

---

11. Accessibility & Maintenance

Accessibility and maintenance ensure Knowledge Base articles remain accurate, usable, and trustworthy over time.

Articles should be written so they can be:

• Read by screen readers

• Skimmed quickly

• Used on mobile or responsive layouts

• Reliably interpreted by AI tools

Avoid unnecessary jargon where possible, and prefer clear, direct language.

Maintenance Expectations

Articles must be reviewed and updated when any of the following occur:

• UI changes that affect labels, navigation, or layout

• Feature releases that change behavior, options, or outcomes

• Support escalation patterns that indicate recurring confusion or errors

Screenshots, links, and examples must be kept current and aligned with the written instructions.

Articles should also be reviewed at least annually to ensure accuracy and relevance.

Clear ownership, consistent updates, and accessibility-first writing ensure the Knowledge Base remains dependable for users and support teams alike.