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
- 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
Formatting
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
Creating a New Project
Subheadings
Subheadings highlight specific sections and should not exceed three hierarchical layers. Use h2
(##) or h3 (###) depending on the level.
Example
Setting Up Your Environment
Notes
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
Note: Remember to save your work frequently to avoid data loss.
Hyperlinks
Use hyperlinks to connect readers to additional relevant information when content is beyond the scope of the current article. For example:
Example
One reference for Australian spelling is the Macquarie Dictionary.
Lists
Begin lists with a colon (:) and follow specific punctuation rules based on whether items are full sentences or fragments.
Example
Essential features include:
- Flexibility
- Reliability
- User-friendliness
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
- Flexible
- Reliable
- User-friendly
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
- Open the application.
- Select ‘File’ from the menu.
- Click ‘Save As’.
Text Formatting
- Italics: Titles, legislation, or user input.
- Bold: Emphasis.
- Bold and Italics: Combined emphasis.
Example
This feature is essential for a positive SplashKit user experience.
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
The system processes three datasets daily and can handle up to 15,000 requests per second.
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)
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
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
Acronyms
Spell out terms on first use, followed by the acronym in parentheses. Use the acronym alone thereafter.
Example
This is the Quality Assurance (QA) process. For all QA-related tasks, refer to the following guidelines.
Capitalisation
Use capital letters for proper nouns. Follow sentence case for all writing, including headings.
Example
The team will visit Melbourne next month.
Verbs
Write verbs in the present tense and maintain consistency throughout.
Example
The system processes data efficiently.
Active Voice
Prefer active voice for clarity and simplicity. Use passive voice only when necessary, such as for feedback or preserving relationships.
Example (Active)
The developer fixed the bug.
Example (Passive)
The bug was fixed by the developer.
Avoid Nominalisation
Avoid converting verbs into nouns, as this can make writing cumbersome.
Example
Instead of “The implementation of the feature was successful,” use “The team successfully implemented the feature.”
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
Write out full words to maintain a formal tone. Avoid contractions to ensure clarity.
Example
Incorrect: The user’s guide can’t be accessed online. Correct: The user’s guide cannot be accessed online.
Tone
Use a conversational tone, be brief, and direct. Avoid unnecessary words and contractions. Use the Oxford comma.
Example
You can find the instructions in the user manual.
Voice
Use the second person (e.g., “You go to the library”).
Example
You should update the software regularly.
Types of Writing
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
Revision Date: July 2024 Version ID: 1.0.0
Code Examples
Provide clear and concise examples for key development tasks. Ensure code is easy to replicate and follows best practices.
Example
print("Hello, world!")