Writing Style Guide
This writing style guide is designed to inform decisions when writing on behalf of Thoth Tech. It is a live document and ensures consistency across all Thoth Tech communications.
Key Principles
Section titled “Key Principles”- Know Your Audience: Tailor your writing to the intended audience’s knowledge level and expectations.
- Know Your Purpose: Understand the intention behind your writing.
- Structure Your Writing: Organise content logically and coherently.
- Keep It Simple: Use clear and straightforward language.
- Review and Edit: Always proofread for clarity, accuracy, and consistency.
Table of Contents
Section titled “Table of Contents”Formatting
Section titled “Formatting”Headings
Section titled “Headings”Headings should be clear and concise, with all content relating to the heading or linking to
relevant information. Avoid using question formats for article headings. Use h1 (#) for main
headings.
Example
Section titled “Example”Creating a New Project
Subheadings
Section titled “Subheadings”Subheadings highlight specific sections and should not exceed three hierarchical layers. Use h2
(##) or h3 (###) depending on the level.
Example
Section titled “Example”Setting Up Your Environment
Use notes for supplementary information necessary for understanding but outside the main content scope. Keep them brief and to the point, with optional links for further reading.
Example
Section titled “Example”Note: Remember to save your work frequently to avoid data loss.
Hyperlinks
Section titled “Hyperlinks”Use hyperlinks to connect readers to additional relevant information when content is beyond the scope of the current article. For example:
Example
Section titled “Example”One reference for Australian spelling is the Macquarie Dictionary.
Begin lists with a colon (:) and follow specific punctuation rules based on whether items are full sentences or fragments.
Example
Section titled “Example”Essential features include:
- Flexibility
- Reliability
- User-friendliness
Unordered/Bullet List
Section titled “Unordered/Bullet List”Use unordered lists for items without a specific order. Begin with a dash (-) and avoid punctuation unless the items are full sentences.
Example
Section titled “Example”
- Flexible
- Reliable
- User-friendly
Ordered/Numbered List
Section titled “Ordered/Numbered List”Use ordered lists for steps or items that follow a specific sequence. Number each item and ensure proper punctuation for complete sentences.
Example
Section titled “Example”
- Open the application.
- Select ‘File’ from the menu.
- Click ‘Save As’.
Text Formatting
Section titled “Text Formatting”- Italics: Titles, legislation, or user input.
- Bold: Emphasis.
- Bold and Italics: Combined emphasis.
Example
Section titled “Example”This feature is essential for a positive SplashKit user experience.
Numbers
Section titled “Numbers”- Write out numbers one through nine; use numerals for 10 and above.
- Use commas for clarity in large numbers (e.g., 25,000).
Example
Section titled “Example”The system processes three datasets daily and can handle up to 15,000 requests per second.
Sentences
Section titled “Sentences”Keep sentences concise, with an average length of 15-20 words, and a maximum of 25 words. Avoid redundancy and ensure clarity.
Example (too long)
Section titled “Example (too long)”The application, which was developed over a period of three years by a team of skilled developers and designers, incorporates a wide range of features that are intended to enhance user experience and improve overall functionality, making it one of the most comprehensive and user-friendly tools available on the market today.
Explanation: This sentence is too long, making it difficult to follow.
Revised Example
Section titled “Revised Example”The application was developed over three years by a skilled team. It includes features to enhance user experience and improve functionality, making it one of the most comprehensive and user-friendly tools available.
Writing
Section titled “Writing”Acronyms
Section titled “Acronyms”Spell out terms on first use, followed by the acronym in parentheses. Use the acronym alone thereafter.
Example
Section titled “Example”This is the Quality Assurance (QA) process. For all QA-related tasks, refer to the following guidelines.
Capitalisation
Section titled “Capitalisation”Use capital letters for proper nouns. Follow sentence case for all writing, including headings.
Example
Section titled “Example”The team will visit Melbourne next month.
Write verbs in the present tense and maintain consistency throughout.
Example
Section titled “Example”The system processes data efficiently.
Active Voice
Section titled “Active Voice”Prefer active voice for clarity and simplicity. Use passive voice only when necessary, such as for feedback or preserving relationships.
Example (Active)
Section titled “Example (Active)”The developer fixed the bug.
Example (Passive)
Section titled “Example (Passive)”The bug was fixed by the developer.
Avoid Nominalisation
Section titled “Avoid Nominalisation”Avoid converting verbs into nouns, as this can make writing cumbersome.
Example
Section titled “Example”Instead of “The implementation of the feature was successful,” use “The team successfully implemented the feature.”
Punctuation
Section titled “Punctuation”| Symbol Name | Symbol | Main Use |
|---|---|---|
| Full Stop | . | End a statement or command |
| Question Mark | ? | End a direct question |
| Exclamation Mark | ! | Express emotion |
| Comma | , | Separate words and groups of words |
| Colon | : | Introduce more information |
| Dash | — | Informal colon or additional information |
| Parentheses | () | Enclose supplementary information |
| Brackets | [] | Enclose words added by someone other than the author |
| Apostrophe | ’ | Show possession or contraction |
| Hyphen | - | Join words |
| Quotation Marks | "" | Enclose spoken words |
Avoid Using Contractions
Section titled “Avoid Using Contractions”Write out full words to maintain a formal tone. Avoid contractions to ensure clarity.
Example
Section titled “Example”Incorrect: The user’s guide can’t be accessed online. Correct: The user’s guide cannot be accessed online.
Use a conversational tone, be brief, and direct. Avoid unnecessary words and contractions. Use the Oxford comma.
Example
Section titled “Example”You can find the instructions in the user manual.
Use the second person (e.g., “You go to the library”).
Example
Section titled “Example”You should update the software regularly.
Types of Writing
Section titled “Types of Writing”Technical Content
Section titled “Technical Content”Technical content should include a table of contents, revision date, and version ID. Tailor it to the reader’s skill level, and define technical terms clearly.
Example
Section titled “Example”Revision Date: July 2024 Version ID: 1.0.0
Code Examples
Section titled “Code Examples”Provide clear and concise examples for key development tasks. Ensure code is easy to replicate and follows best practices.
Example
Section titled “Example”print("Hello, world!")