How We Write: The Literally Style Guide for Technical Content

At Literally, we’re passionate about turning complex ideas into clear, accessible, and useful content. As a technical communication company, we know that great writing isn’t just about accuracy, but creating content that resonates with readers and meets the unique needs of our clients.

In this post, we’ll walk you through how our style guide works, why it matters, and what it says about our approach to technical writing.

‍

Why a Style Guide Matters

Every piece of technical content we create has a purpose. It might teach a developer how to use an API, explain best practices for deployment pipelines, or guide teams through troubleshooting complex systems. But without a style guide, even the most informative content can seem sloppy and daunting to consume.

Here’s why a style guide is critical for technical writing:

1. Consistency Across Writers and Projects - With multiple writers working across various projects, a style guide ensures that every piece feels cohesive and aligned. This consistency builds trust with readers and reinforces your brand’s voice.
2. Clarity in Communication - Developers are busy. They don’t have time to decipher unclear documentation or inconsistent terminology. A style guide prioritizes plain English, active voice, and logical structure, ensuring your audience gets the information they need quickly.
3. Efficient Collaboration - Whether we’re working with in-house teams or client stakeholders, a style guide streamlines the content creation process by setting clear expectations from the start.

‍

Our Style Hierarchy

At Literally, we understand that every client has unique preferences. To accommodate this, we use a style hierarchy that prioritizes flexibility while maintaining high standards:

1. The Client’s Style Guide - If a client provides their own style guide, it takes precedence. This ensures all content reflects their brand’s specific tone, structure, and formatting guidelines.
2. The Literally Style Guide - In the absence of client-specific guidelines, we rely on our internal style guide. It’s designed to ensure clarity, consistency, and readability across all technical content.
3. Fallback Guides - For edge cases, we refer to established industry standards, such as:
   • Chicago Manual of Style for grammar and formatting.
   • Merriam-Webster’s Dictionary for resolving spelling or usage questions.

This hierarchy ensures we can adapt to client needs without sacrificing quality or consistency.

‍

Writing the Literally Way

Our writing process starts with understanding our client’s goals and audience. From there, we develop content that balances technical depth with accessibility, ensuring it speaks to developers without alienating less-technical readers.

Here’s how we apply our style guide in practice:

• Client Input: If the client has specific guidelines or preferences, we incorporate them into our process.
• Content Outlines: Before writing begins, we create detailed outlines aligned with the client’s goals and tone.
• Style Guide Application: Our internal standards shape everything from word choice to formatting, ensuring every piece is polished and professional.

This process guarantees that every article, tutorial, or guide isn’t just accurate but enjoyable to read.

‍

Our Guidelines in Practice

Our style guide reflects our approach to technical content: clear, consistent, and user-focused.

Voice and Tone

Aim for a tone that’s professional yet conversational—think “business casual.” Active voice, plain English, and brevity are essential. Contractions and occasional sentence fragments are acceptable if they make the content more approachable.

Markdown

All posts should be written in Markdown, a lightweight markup language that’s perfect for technical content. If you’re new to Markdown, you can learn more from resources like Daring Fireball.

File Formatting

Keep each source line under 120 characters, except when including long URLs. This makes reviewing and commenting on Pull Requests easier.

Headers

Title

• Every content piece begins with an H1 header that serves as the title. This should always be the first in the file.

Header Formatting

• Use Markdown’s hash marks (##) for headers rather than underlined syntax.
• Write all headers in title case, as outlined in the Chicago Manual of Style. For example:
  • Capitalize the first and last words and all major words (e.g., nouns, verbs, adjectives).
  • Articles (a, an, the), coordinating conjunctions (and, but, or), and short prepositions (in, on, at) remain lowercase unless they’re the first or last word in the title.
• When in doubt, tools like Capitalize My Title can help.

Introduction

The opening paragraph should set the stage for the post. Include the goals, tools, and methods, and give readers a preview of what they’ll learn. Make it engaging to encourage them to read on.

H2 Sections and Subheadings

• Provide at least one sentence under each header to explain its purpose. Avoid jumping from one header to another without context.
• Use H2 and H3 headers only; avoid H4 and smaller headers to keep formatting consistent.

Code

Technical content often revolves around code, so we have clear guidelines for presenting it:

Code Formatting

Use code formatting for:

• Code snippets
• File names and scripts
• Commands and outputs
• Inline items like function names or file paths

Each code block must have an explanation that describes its purpose. For example:

npm install axios --save


Install the axios npm package.

‍

When appropriate, include the file name as a comment in the first line of a code block. This is particularly helpful in frameworks with specific conventions.

Code Snippets

• Use triple backticks (```) to format code blocks and include a language identifier (e.g., bash, ruby, python) for syntax highlighting.
• Start explanations with clear, concise sentences. Examples:
  • Create an empty Node.js project:
  • At this point, your project directory should look like this:

Inline Code and Commands

Inline code is useful for referring to:

• Command names (e.g., mkdir)
• File paths (e.g., app/main.js)
• Method arguments (e.g., filename)
• Example URLs (e.g., http://example.com)
• Function names
• File and directory names, paths like app/hello_world.js
• Options like latr
• Key presses like ENTER
• Ports like :8080

Avoid using inline code for commands the reader needs to execute. Use full code blocks instead, with explanations for options and flags.

Links and Images

Links

• Use standard Markdown link syntax and avoid extra formatting.
• Keep linked text meaningful (e.g., Follow along with this GitHub repository instead of Click here).

Images

• Use .png format and keep images at least 1320px wide.
• Add descriptive alt text for accessibility.
• Types of images we use:
  • GUI screenshots
  • Technical diagrams (must be original; no screenshots of other diagrams)

Avoid using  images of console output. Commands and output should be included as code-style text so they can be copied.

Text Styles

Bold

Use sparingly for:

• Notes or warnings (Note: or Warning:).
• Key terms in lists (e.g., Command: Used for navigation).

Italics

Use italics to introduce technical terms or emphasize important concepts. Example:

• Continuous integration (CI) is a development practice.

Lists

• Use unordered lists for prerequisites, checklists, or additional resources

Wrapping it Up

No technical content piece should end abruptly. Wrap up with a brief conclusion summarizing what readers accomplished and suggest logical next steps they can take.

‍

By following these guidelines, we ensure every piece of content reflects Literally’s commitment to quality and consistency. Whether it’s a blog post or detailed documentation, our goal is to make the content intuitive, engaging, and easy to follow.

‍

Conclusion

At Literally, our style guide is more than a set of rules — it’s the foundation of our approach to technical writing. It ensures clarity, consistency, and quality, while remaining flexible enough to meet our clients’ needs.

Whether you’re looking for engaging blog posts, user-friendly documentation, or clear tutorials, you can trust us to deliver content that’s accurate, polished, and enjoyable to read.

Would you like to learn more about how we approach technical writing? Get in touch! We’d love to help elevate your content!