Skip to content

Latest commit

 

History

History
135 lines (86 loc) · 2.81 KB

STYLEGUIDE.md

File metadata and controls

135 lines (86 loc) · 2.81 KB

TACC Technical Documentation Style Sheet

Last update: February 11, 2025

Point of View / Voice

Employ the second-person "you" addressing the user in a familiar voice. This is not consistent across TACC user guides, though later guides do employ this voice.

Formatting

"Last update:" Date

Only amend for significant content updates, not formatting or typos. At top of document, hand-marked.

Last update: Month day, year

Last update: January 7, 2025

Tables

"Table X. Description" must be anchor'd in succession e.g #table1.

Images

All figures styled with <figure> and <figcaption>

Figure X. Description - all anchor’d

Punctuation

  • Use serial comma
  • Use old-school two spaces after each period. It helps with readability. And I like it.

Numbers

  • Format dates: June 2, 2022
  • Use en dash (instead of hyphen) for ranges.

Units

Express Storage/Memory capacity:

  • 123GB not 123 GB

Style

  • Use quotation marks around Unix command names on their first mention; drop quotation marks thereafter e.g.

    "Use the "`taccinfo" command to see your allocations. taccinfo will display your current balances"

  • Acronyms / initials - spell it out once, then introduce the acronym. Use acronym thereafter.

    "Consult the TACC User Portal (TUP) for further info."

  • Follow Chicago's guidelines regarding the treatment of numbers as words and numerals.

  • Employ headline-style capitalization in section headings.

Technical Terms

Much as I want to do "filesystem" I don’t think we’re there yet, hence separate words:

  • "file spaces" not "filespaces"
  • "file systems" not "filesystems"
  • "work space" not "workspace"

Code Styles

Job Script

#SBATCH -N 10 -n 40
...
ibrun myexectublew

Syntax

time [-al] [-h | -p] [-o file] utility [argument ...]

Code

// inner loop strides through row i  
for (i=0;i<m;i++){  
    for (j=0;j<n;j++){  
        a[i][j]=b[i][j]+c[i][j];  
}

Command-line Prompts

Always denote a proper login prompt for command-line examples.

Login Node ```cmd-line login1$ sbatch myscript ```
Laptop/Other 
localhost$ ssh frontera.tacc.utexas.edu
Compute node ```cmd-line c455-301$ top ```
Default
Use simple Bourne-shell prompt		 ```cmd-line $ date ```