Documentation Guidelines

General

  • Write easy-to-follow directions
  • Use correct grammar and mechanics
  • Omit unnecessary words
  • Use consistent formatting

Lists

  • Do not create a list of fewer than two items
  • Bullet points vs. numbers
    • Use bullet points for general lists
    • Use numbers for directions that must be completed in the order listed
  • Do not put punctuation at the end of list items
    • Exceptions: ? and !
  • Links that navigate to a page outside of support.britecorepro.com or briteedu.squarespace.com should open in a new tab using the code below
    <a href="URL" target="_blank">Text for hyperlink</a>
  • Links that navigate to a page within the support site should open in the same tab
    • Exception: "Report" link under Feedback
    • To not open a link in a new tab, use [this is my text](this is my link)

Images

  • Ensure images appear
  • Enable Lightbox on images
    1. In the Edit Image window, click the Design tab in the upper right corner
    2. Scroll down
    3. Click the bubble beside Enable Lightbox
    4. Click Apply

Formatting Guidelines

Basics

  • Use SquareSpace Markdown blocks
  • Text = Effra
  • Use <span class="warn"></span> for warnings
  • Use <span class="note"></span> for tips
  • When referencing tickets, use the phrase Submit a ticket to IWS
  • Use all caps for file names (PDF, XLS, TXT) and other miscellaneous things like JSON and URL
  • Use &#8805; for ≥ and &#8804; for ≤
  • When documenting database settings, use word-word-word
  • For emails, use the phrases The below email is sent or Recipients receive an email like the below

Heading Hierarchy

#
##
### 
####
** **

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Code

  • For inline code, surround the word or phrase with tick marks
  • For large blocks of code use
    <code class="codeblock">This the codeblock.</code>
  • For large blocks of code within a list use three tick marks, ```, before and after the code
    code block

Contacts

name
title
801.492.7013 (P) | 650.286.6656 (F)
email

How-Tos Structure

The title of each how-to should be a 2nd-level heading. When there are many how-tos, use a table of contents or headers:
Header 1

  • Item 1
  • Item 2

Header 2

  • Item 1
  • Item 2

When creating a link to a hyperlink within the text, use the following format: Name of How-To how-to.

FAQ structure

This is the question. If there is a title, use italics. End with a ?
Answer.

Feedback structure

  • Add a Feedback section to each page
  • Use the following format
    # Feedback  
      <a href="https://briteedu.squarespace.com/documentation-blog/updates" target="_blank">Report</a> unclear or missing documentation.

Page Title

In the designated header section of a page, employ <div class="pagetitle">Quickbooks</div> for the page title.

Images

SquareSpace does not export images. For this reason I originally chose to store images in Google Drive then link them in SquareSpace (process detailed below). This worked well until some SquareSpace update killed the link. Given this, I now upload images directly to SquareSpace but do so sparingly.

  • Use the SquareSpace image block to insert an image

OLD PROCESS
1.Use .png files
2.Title the photo providing a general idea of the page, section and image #. Use underscores. Example Claims_CoreConcepts_Image1.png
3.Access the BriteEdu Assests Google Drive folder
4.Locate the folder for the page. If one does not exist, create the folder with a title that describes where the page is located on the site
5.Upload the photo(s) to the folder
6.Locate in BriteEdu where you want the photo to appear
7.Use the Image block
8.Upload the image

Workflow Diagrams

  1. Use Draw.io to create the diagram
  2. Title the diagram providing a general idea of the workflow. Use underscores. Example Claims_Workflow_Raw_File.
  3. Access the BriteEdu Assests Google Drive folder
  4. Locate the folder for the page. If one does not exist, create the folder with a title that describes where the page is located on the site.
  5. Upload the file to the folder
  6. Export the diagram as PNG and SVG
  7. Grab the sharable Google Drive link
  8. Locate in BriteEdu where you want the photo to appear
  9. Use the Image block
    • Upload the PNG
    • At the bottom, click the Click to add URL
      • Select Files
      • Upload the file
      • Click Open in New Window
  10. Add this to the markdown under the workflow header
    Click on the image below to open in a new window. Access the raw file [here][1].

Page Templates

Main page

Search bar
[Preliminary Work]
[Key Decisions]
Core Concepts
[Settings]
How-To’s
FAQs
[More Info]
Feedback

Supplemental Page

Core Concepts
[Examples]
BriteCore Setup
[FAQ]
Feedback

Table of Contents

  • [Name on screen](#this-is-the-exact-header-title-in-all-lowercase)

Tables

  • Insert a squarespace code block
  • Basic template
    <table class="mytable" id="tabletab">
      <tbody><tr>
        <th>Module</th>
      </tr>
      <tr>
        <td>Contacts</td>
      </tr>
      </tbody></table>
  • Add ons
    • <table class="mytable text--left"> aligns all text to the left
    • <span class="text-secondary">text</span> adds secondary text under the main text of the table