This guide builds on the Google developer documentation style guide. When something isn't covered here, follow Google's guidance. If it's still not clear, choose the option that is easier to read, scan, and understand.
Xorq is always written with a capital X in body text, headings, and UI copy.
In code, commands, and config, match the API/CLI syntax exactly. Don't override what the code expects.
| Context | Correct | Wrong |
|---|---|---|
| Body text, headings | Xorq | xorq, XORQ, XOR |
| Code, commands, config | Match API/CLI syntax exactly | Don't "fix" casing in code |
Use official names for core concepts: build, node hash, backend, profile.
Define each term once in a Concepts or Glossary page, then use it consistently everywhere.
Don't use them.
- Write "for example" instead of "e.g."
- Write "that is" instead of "i.e." (Google guidance)
Use "people with disabilities", not "the disabled" or "disabled people" (Google guidance).
Write like you're talking to a professional data engineer who knows their field but doesn't have time for marketing speak.
Be direct. Be helpful. Skip the hype.
| Good | Bad |
|---|---|
| Use Xorq to build a pipeline that runs on DuckDB. | Xorq is an innovative next-generation orchestration engine that revolutionizes data workflows. |
| Configure the backend in the profile file. | Leverage our cutting-edge configuration paradigm to unlock backend power. |
Focus on what the user is trying to do, not on how impressive Xorq is.
Use second person ("you") to talk to the reader.
Use present tense unless you're describing something that happened in the past.
| Good | Bad |
|---|---|
| You configure the backend in the profile file. | The user will configure the backend. |
| Xorq builds the pipeline and writes output to the builds directory. | Xorq will build the pipeline and write output. |
| Run the command, then check the logs if you see an error. | After you have run the command, which might take several minutes depending on your environment, you should then proceed to inspect the logs in the event that any errors occurred. |
Avoid "we" unless you clearly mean the Xorq team (for example, in release notes or roadmap statements).
One main idea per sentence.
Keep paragraphs short — two to four sentences.
Avoid nested clauses when a simpler structure works.
Write so people can quickly scan the docs and find what they need.
Use sentence case for all headings (H1 through H6).
Make headings descriptive, not cute.
| Good | Bad |
|---|---|
| Run a build with DuckDB | Run A Build With DuckDB |
| Serve a pipeline with xorq serve-unbound | Let's go live |
| Configure the profile file | Profile magic happens here |
Every page must have one H1 that states the topic clearly, plus logical nested headings (H2, H3) to break content into scannable sections.
Use consistent documentation types across the docs. Each page should have one clear purpose. Don't mix tutorial content with reference material on the same page.
| Type | Purpose | Example |
|---|---|---|
| Quickstart | Get to a first successful build or run as fast as possible | "Get started with Xorq in 5 minutes" |
| Tutorial | Step-by-step, learning-focused walkthrough that takes the reader by the hand | "10-minute tour of Xorq" |
| How-to guide | Task-based instructions for specific goals that assume some existing knowledge | "How to serve a pipeline with Xorq and DuckDB" |
| Reference | API, CLI, config, and schema details | "xorq build command reference" |
| Concept | Explanations of ideas and architecture | "Deferred execution", "Multi-engine", "Profiles" |
Tutorials are learning-oriented and assume the reader is a beginner. You're responsible for deciding what the reader needs to know and what they should do. The tutorial takes them by the hand through a series of steps to complete a meaningful project.
How-to guides are goal-oriented and assume the reader already has some experience. They answer questions that only someone with existing knowledge would ask: "How do I…?". The reader knows what they want to achieve but doesn't yet know how.
Use bullet lists for unordered information.
Use numbered lists for sequences and procedures.
Example procedure:
- Install the required backend.
- Configure your profile.
- Run
xorq buildwith your script. - Serve the generated build.
Use tables for parameter lists, flags, and comparisons.
Don't use tables for layout.
Keep headers short and descriptive.
| Flag | Description | Default |
|---|---|---|
--builds-dir |
Directory where build artifacts are stored | builds |
--engine |
Execution engine to use | expr |
Code and CLI examples are critical in Xorq docs. Follow these guidelines:
- Use fenced code blocks with the correct language hint (
bash,python,sql, and so on). - Separate input and output. Show the command in one block, then show the output in another block, labeled as output.
Good example:
xorq build penguins_analysis.py -e expr --builds-dir buildsOutput:
Build complete. Wrote manifest to builds/45f3bdbdb521/manifest.json
Don't put long comments inside commands users will copy and paste. Explain the command above or below the code block instead.
Use clear placeholders in angle brackets and explain them once per page:
xorq serve-unbound builds/<build_id> --host localhost --port 8001Then explain: "Replace <build_id> with your actual build directory name (for example, 45f3bdbdb521)."
If commands differ on Windows, macOS, or Linux, show each explicitly and label them. Don't assume only bash or zsh.
Make link text descriptive. Don't use "click here" or raw URLs. (Google guidance)
| Good | Bad |
|---|---|
| See the CLI reference for xorq build. | Click here. |
| Read about deferred execution in the Concepts guide. | More info at https://docs.xorq.dev/concepts |
Link to related tutorials and how-to guides, concept pages that explain jargon, and reference pages for flags, options, and API details.
Every major page should have "Next steps" links at the end.
Use screenshots when they clarify an important step or result—showing the builds folder and manifest, or a successful served pipeline, for example.
Add alt text that describes what the user should notice, not just "screenshot." (Google guidance)
| Good alt text | Bad alt text |
|---|---|
| Screenshot of the builds directory showing manifest.json in the 45f3bdbdb521 folder. | Screenshot |
| Terminal output showing successful build completion with node hash. | Image of terminal |
Don't use images as the only way to convey critical information.
Write and structure docs so they work for people with disabilities and for people on different devices. (Google guidance)
- Use clear headings and logical structure.
- Use proper list markup for steps and bullets.
- Write meaningful link text (not "here" or "this").
- Include alt text for images.
- Avoid overly complex tables and deep nested lists when a simpler structure works.
Avoid terms that stereotype or exclude. Use neutral, precise language.
Prefer "you" over "the user" when speaking to the reader.
| Good | Bad |
|---|---|
| developers, data engineers | rockstar developers, ninja coders |
| people with disabilities | the disabled, the handicapped |
| example data, test data | dummy data for idiots |
When in doubt, check the Google style guide's word list and accessibility guidance.
Use numeric form for 10 and above. Spell out one through nine, unless it's a unit or parameter.
Examples:
- "You can run up to 3 builds in parallel."
- "The cluster has 16 workers."
Use unambiguous formats in docs.
| Good | Bad |
|---|---|
| 21 November 2025 | 11/21/25 |
| 2025-11-21 (in code or logs) | 11/21/2025 |
Use SI units and be consistent (MB versus MiB, for example) when it matters.
When you document UI labels, flags, or error messages, match the UI text exactly (including case).
Use formatting to make it clear:
- Buttons: bold → "Click Run build."
- Flags or keys: code → "Set
builds-dirin the config."
For error messages, quote them exactly, then explain what they mean and what to do next.
Error:
Error: Backend not found for engine 'duckdb'
What it means: The DuckDB backend isn't installed or configured in your environment.
What to do: Install the backend with pip install "xorq[duckdb]" and verify your profile configuration.
Every page should answer one clear question.
| Page type | Question it answers |
|---|---|
| Quickstart | How do I get my first pipeline running? |
| How-to | How do I serve a pipeline? |
| Reference | What flags does xorq build support? |
| Concept | What is deferred execution and why does it matter? |
Keep sidebar hierarchy shallow and intuitive. Avoid deep nesting. Avoid duplicate or near-duplicate topics with small differences.
Connect sections so the reader always knows where they are and where they're going next.
Good example:
"With header normalization all set, the next step is to make sure caching is working perfectly.
Each section should bridge to the next one. Tell readers what they just finished and what comes next. This keeps them oriented and prevents them from feeling lost.
Don't use marketing language or jargon that clutters technical documentation. Avoid these words and phrases entirely:
- Foster
- Revolutionize (use "transform" instead, except in narratives)
- Landscape (especially "in the fast-paced tech landscape...")
- Underscoring
- Seamless (avoid or reduce usage)
- Robust (avoid or reduce usage)
- Streamline
- Delve
- Dives deep
- Elevate
- Realm
- Facilitate
- Groundbreaking
- Evolve
- Emergence
- Comprehensive (avoid or reduce usage)
- "Dives deep"
- "This is where x comes in"
- "X is not just about; it's about"
- "X isn't just nice to have; it's..."
- "You're not alone"
- "Thrive in a fast-paced environment"
- Ensure (appears multiple times in articles—keep to 2-3 instances)
- Enhance (often overused—reduce to 2 per page)
- Significant(ly) / Effective(ly) (often overused—reduce to 2-3 instances)
- Essential (often overused—reduce to 2-3 per page)
- Em dashes (—) (often overused—reduce to 2-3 instances)
These words add nothing. Cut them. Write plainly instead.
Use these terms consistently across all Xorq docs. When in doubt, refer to the Google word list and this table.
| Term | Usage | Notes |
|---|---|---|
| Xorq | Always capital X | Except in code where syntax demands otherwise |
| Quickstart | One word, capital Q | When used as a title ("Xorq Quickstart") |
| backend | Lowercase in running text | Unless part of a formal name |
| profile | Lowercase in running text | Use code formatting when referring to a key or field |
| build | Lowercase | As in "run a build" |
| builds directory | Lowercase | The directory where builds are stored |
| node hash | Lowercase | Unique identifier for a node in the execution graph |
| manifest | Lowercase | The JSON file containing build metadata |
Define each term once in the Concepts section, then use it the same way everywhere.
When you write or review Xorq docs:
- Start with this style guide and the Xorq-specific decisions.
- If something isn't covered here, follow the Google developer documentation style guide.
- If it's still unclear, choose the option that is easier to read, scan, and understand.