Writing

Our Writing Philosophy

At Alephic, writing is our primary tool for clarity and persuasion. The written word reveals our thinking, demonstrates our expertise, and builds trust with clients. This style guide helps us maintain a consistent voice that embodies intellectual depth without sacrificing accessibility.

Core Writing Principles

1. Write with Vigor and Concision

A sentence should contain no unnecessary words, a paragraph no unnecessary sentences—just as a drawing should have no unnecessary lines and a machine no unnecessary parts.

— Strunk & White

• Say it once. Strike any word, sentence, or paragraph that doesn't earn its keep. (If your eyes glide past a line on reread, that line's a goner.)
• Move on when the point is made. Redundancy clouds insight; brevity sharpens it.
• Cut ruthlessly, then cut again. Before you hit "publish," skim the piece at speed—whatever phrase jumps out without advancing the argument is your extra earring. Snip it.

Remember: concise doesn't mean short. Depth is welcome—every sentence just has to pay rent.

2. Use Active Voice

• Lead with the doer. Put the actor before the action: "AI transforms marketing," not "Marketing is transformed by AI."
• Write subject-verb-object by default. Active structure keeps sentences short, direct, and energetic. (Passive voice is fine when the actor is unknown or irrelevant—but use it knowingly, not lazily.)
• Let verbs carry the load. Prefer "We built a real-time dashboard" over "A real-time dashboard was built." Strong verbs clarify responsibility and speed understanding.

3. Be Specific and Concrete

• Put a number on it. Ground every claim in data and context: "U.S. bureaucracy costs ≈ $3 T—about 17% of 2016 GDP" beats "Bureaucracy is expensive."
• Name your evidence. Cite the dataset, quote the expert, and link the study. Specific sources build instant credibility.
• Swap abstractions for examples. When possible, replace "organizations often …" with a specific company, project, or metric that readers can visualize.

4. Structure for Clarity

• One idea per paragraph. Open with a topic sentence; let each paragraph advance a single step.
• Signal the hierarchy. Use clear headers (H2 → H3 → H4) so readers can skim the shape before reading the words.
• Give text room to breathe. Break dense blocks into short paragraphs and add deliberate white space.

Our Voice

Our voice balances three key qualities:

1. Intellectually Bold

We challenge conventional thinking, make unexpected connections, and offer fresh perspectives.

Example:

At the intersection of AI, code, and marketing expertise, we create solutions that were impossible yesterday and will be commonplace tomorrow.

2. Ambitiously Grounded

We paint visions of transformative change while keeping one foot firmly in practical reality.

Example:

This is just the beginning. If these models never got better than what we have today, there would still be 10 years of runway to operationalize them.

3. Radically Simple

We present complex ideas with clarity and confidence, stripping away all unnecessary elements.

Example:

With AI, impossible problems become merely hard, hard problems become easy, and easy problems become trivial. All the fun is in expanding the boundaries of what is possible.

Tone Characteristics

Our writing should feel:

Conversational

Be serious and smart in a casual way. Write as if you're an optimistic, excited person sharing ideas you genuinely care about. Avoid corporate-speak and jargon that creates distance.

Thoughtful

Ground your writing in thoughtful analysis. If we're betting our future on understanding the market better than our competitors, then everything we write should demonstrate genuine thought.

Clear and Concise

Smart doesn't mean wordy. Use fewer words when possible. Have a good vocabulary, but keep things simple to help others understand our vision. Read your writing and clarify anything someone might not understand on the first pass.

Bold

Make strong statements that position us as leaders and experts, but always be prepared to back them up with evidence. Bold doesn't mean negative – remain excited about the industry and optimistic about the future.

Documentation Best Practices

Our approach to documentation incorporates these key principles:

1. Fit for Context

Determine what type of documentation you're writing:

• Tutorials - Learning-oriented guidance for beginners
• How-to guides - Task-oriented directions for specific problems
• Reference material - Information-oriented technical descriptions
• Explanations - Understanding-oriented discussions of concepts

2. Clearly Written and To The Point

Get to the point. Make your point. Get out of the way.

3. Visual Where Possible

Utilize diagrams, screenshots, charts, and other visual aids to clarify complex concepts. For software documentation, use animated GIFs or videos when static images won't suffice.

4. Skimmable

Structure content to help readers identify and skip over familiar concepts. Use headings, links, lists, paragraphs, and bolding to make your document scannable.

5. Up to Date

Outdated documentation does more harm than none at all. Set regular check-in dates, split documentation when possible to minimize update requirements, and create channels for feedback.

6. Discoverable

Ensure your documentation is easy to find, properly categorized, and shareable. Treat documentation as a critical part of our shared organizational memory.

Editing Process

Collaborating with AI

AI is our creative co-pilot, not an autopilot. We draft, outline, or brainstorm with language models, but always read and refine AI output before sharing. It's discourteous to pass along writing you haven't read.

• Review line by line. Never forward raw AI output. Read it aloud and refine the voice so that it feels unmistakably your own.
• Verify facts and sources. Treat model-generated references as unverified until you confirm them.
• Own the byline. Only ship content you'd proudly sign—AI can assist, but you own the final version.

The HAL 9000 Rule

I'm sorry, Dave, I'm afraid I can't let you edit that.

— 2001: A Space Odyssey (paraphrased)

Finally, and most importantly, don't let AI (or any editor) remove you from the writing. The natural desire of Grammarly or ChatGPT is towards best practices. Great writers have their own style and are comfortable in it. It doesn't mean you can break basic rules of grammar (though sometimes you can), but watch out for the flattening effect these tools can have on the things that make you unique. Just because the machine tells you to do it doesn't mean you have to do it.

The Four-Question Test

When editing a document, ask yourself:

1. Is it clear? Have I made my point explicitly?
2. Is it concise? Have I used more words than necessary?
3. Is it insightful? Am I bringing new ideas to the table?
4. Is it compelling? If I'm asking the reader to take action, why will they do it?

The "LA Story Test"

In the 1991 film L.A. Story, Trudi lays out her "seven-point jewelry" rule: never leave the house wearing more than seven "points" (earrings count as two, a necklace one, and so on). Before stepping out, she spins in front of a mirror—the first item that catches her eye gets removed.

Apply the same ruthless minimalism to prose. On your final pass, skim the piece quickly; whatever phrase, sentence, paragraph, or section jumps out but doesn't advance the argument is your extra earring. Cut it.

Right before you go out, look in the mirror and turn around real fast, and the first thing that catches your eye—get rid of it.

— L.A. Story (1991)

The "Blurry Eyes" Test

When you find yourself skipping over a sentence or paragraph while editing, you've found your place to cut.

The Six-Step Process

1. Draft - Get your ideas down without worrying about style
2. Structure - Organize your content with a clear hierarchy
3. Edit - Apply Strunk & White principles:
   • Omit needless words
   • Use active voice
   • Be specific and concrete
   • Check your paragraphs for unity and coherence
4. Apply the editing tests - Use the four-question test, LA Story test, and blurry eyes test
5. Read aloud - Test for natural flow and rhythm
6. Finalize - Check formatting, links, and references

Grammar and Punctuation Guidelines

Commas

• Use the Oxford comma (the final comma in a list of three or more items).
• Use commas to separate independent clauses joined by coordinating conjunctions (and, but, or, nor, for, so, yet).
• Use commas after introductory clauses and phrases.
• Use commas to set off nonessential information.

Dashes and Hyphens

• Use em dashes (—) for abrupt breaks in thought and as a stronger alternative to commas or parentheses. We don't use spaces around our em dashes.
• Use en dashes (–) for ranges (2–3 weeks).
• Use hyphens (-) to form compound adjectives (AI-powered solution).

Capitalization

• Headlines (H1/H2): Use Title Case — capitalize the principal words.
• Subheads (H3 and below): Use sentence case unless a design system specifies otherwise.
• Capitalize proper nouns, including branded terms.
• Do not capitalize generic terms unless they begin a sentence.

Numbers

• Spell out numbers zero through nine; use numerals for 10 and above.
• Use numerals for all measurements with units.
• Use numerals for dates, times, percentages, and currency.
• Use commas in numbers 1,000 and above.
• Use "1800s/1900s/2000s" instead of "19th/20th/21st century". Using century numbers is confusing for many people because the 19th century actually refers to the 1800s. For clarity, always use the specific years.
• Use "$1 T / $500 B / $50 M" abbreviations in headings and slide titles; in body copy, spell the figure once and add context (e.g., "≈17% of 2016 GDP").

Abbreviations: i.e. vs e.g.

• Use i.e. (id est, "in other words") to clarify or restate the previous clause.
• Use e.g. (exempli gratia, "for example") to introduce illustrative examples.
• Mnemonic: i for in other words; e for example.
• Always place a comma after the abbreviation (i.e., … / e.g., …).

Examples

I plan to visit many European countries, e.g., Portugal, Spain, and France.

I plan to visit many European countries, i.e., I have a very full itinerary.

Usage of "data"

Treat data as a mass noun—write "data is" rather than "data are," unless a strictly academic style guide requires the plural. "Data are" often sounds needlessly pedantic in client-facing writing.

Point of View

Use we when representing Alephic's collective stance (website copy, documentation, and other unsigned content). Use I for signed essays or personal anecdotes. Whichever point of view you choose, retain the same bold, grounded, and simple voice.

Headlines and Hooks

• Craft an H1 of 10 words or fewer that states the key tension or surprise.
• Follow with a one-sentence deck/lede explaining why it matters.
• For slides or hero copy, keep lines under 12 words and favor parallel structure.

Evidence & Citation

• Link the first credible source for any statistic, quote, or external concept.
• Whenever you present a number, add context (percent, timeframe, benchmark).
• Use in-text hyperlinks; footnotes only when multiple citations would clutter the flow.
• Include the source name if the link text isn't self-explanatory.

Jargon & Buzzword Filter

Avoid empty buzzwords. If a technical term is essential, give a one-line definition. Words we cut on sight: synergy, disruption, digital transformation, leverage (as a verb), paradigm shift.

Documentation Style

• Address the reader as you; use imperative verbs ("Click Save").
• Present steps in numbered order, one action per step.
• Provide a screenshot, GIF, or code sample for every major action.
• Skip metaphors or storytelling—documentation is for doing, not convincing.

Slide & Deck Style

• Headings may be Title-Case or ALL CAPS to match the design.
• One clear idea per slide, supported by ≤12-word micro-copy.
• Include exactly one visual unless the slide is data-dense.

Case-Study Template

Visual Standards

• Long-form articles: aim for one visual every ~600 words.
• Slides: one graphic per slide unless content-heavy.
• Caption visuals with what and why.

Numeric Abbreviations

Use $1 T, $500 B, $50 M in headings or slide titles. In body text, spell the figure once and add context.

Final Note

Remember that good writing at Alephic isn't about sounding smart—it's about being understood. The clearest voice in the room is often the most powerful.

Writing scales incredibly well. It can be read at any time by an unlimited number of people. Inside our company, writing serves to communicate, converse, think, and archive our collective intelligence.

Our documentation and our writing are our history. The more precise, up-to-date, and detailed that history is—and the more people that contribute to the "story" it tells—the more likely we are to recognize what doesn't work and replicate what does.

Changelog

• May 2, 2025: Added rule about using "1800s/1900s/2000s" instead of "19th/20th/21st century" for clarity in the Numbers section.
• April 30, 2025: Initial draft of the writing guidelines.