Writing Style

Tone and Voice

Write like a patient senior developer sitting next to the reader, not like a textbook:

• Direct and conversational. Use "you" and "we" freely. Prefer short sentences. It is fine to start sentences with "And" or "But" when it reads naturally.
• No purple prose. Skip grandiose language. The reader came here to ship code, not to be told that a framework "empowers developers to unlock the full potential of" something.
• Opinionated but honest. State what we recommend and why. When there are trade-offs, name them. Do not pretend every choice is equally valid.
• Assume competence, not familiarity. The reader knows Java/OOP but has not built an API yet. Do not explain what a class is. Do explain anything Spring Boot-specific that is not obvious.
• Show, do not tell. Every concept gets a code example. Do not write a paragraph describing what code does when a snippet plus a one-liner will do.

Document Openings

Every document should start with a brief introductory paragraph — one or two sentences that orient the reader. This paragraph should convey what the document covers and connect it to what came before.

Phrases like "In the previous document" work well and can be varied (e.g., "Last time," "Previously," "Building on what we set up"). The goal is to give the reader a quick anchor before diving into details.

Example:

In the previous document we set up build-time entity generation from the Sakila schema. This document wires those entities into the hexagonal architecture so the app can query the database.

Files Overview

When a document involves creating or modifying files, add a "Files Overview" section early (after the opening paragraph, before the main content). Use the FileTreeInfo component from src/components/file-tree-info.tsx to present the file tree.

The file tree must live in a separate .tsx file — not inline in the .mdx. Place it under src/components/docs/<section>/<doc-name>.tsx and export a FileTree component. Then import and render it in the .mdx:

// src/components/docs/persistence-integration/database-setup.tsx
import CodeBlock from '@theme/CodeBlock';
import { FileTreeInfo } from '@site/src/components/file-tree-info';

export const FileTree = () => (
  <FileTreeInfo>
    <CodeBlock language="log" title="File Tree">{`
springboot-demo-projects/
├── build.gradle
└── src/
    └── ...
    `}</CodeBlock>
  </FileTreeInfo>
);

// docs/persistence-integration/database-setup.mdx
import { FileTree } from '@site/src/components/docs/persistence-integration/database-setup';

<FileTree />

Use // highlight-added-start, // highlight-added-end, and // highlight-modified comments to mark new and changed files in the tree. Apply these comments to files or groups of files, not to folders. Highlighting folders adds noise and makes it unclear which specific files changed.

Code References

When referencing code, consider the size of the file being referenced:

• Under ~400 lines: inline the full file or relevant sections as code blocks.
• 400+ lines: do not reference the entire file. Instead:
  • Show only the relevant section(s) with a comment like // ... rest of the file unchanged for omitted parts.
  • Or describe what the code does and what changed in a sentence or two, without including the full file.
  • Never dump a 400+ line file into a document. The reader will skip it anyway.

Language Tabs

The project supports three JVM languages (Java, Kotlin, Groovy). Use <Tabs groupId="language" queryString> when content differs across all three (or two) languages. However, when something only applies to one language, skip the tabs entirely — just show the reference directly. Wrapping a single-language snippet in tabs adds indirection with no benefit.

Example — don't do this:

<Tabs groupId="language" queryString>
<TabItem value="java">
<!-- Only Java content here, identical across tabs -->
</TabItem>
<TabItem value="kotlin">
<!-- Same content, no difference -->
</TabItem>
</Tabs>

Instead, just write the content directly.

Identical code across projects

The same rule applies when code is identical across projects (not just languages). This happens frequently with YAML files, Gradle build scripts, and similar config — the content is the same whether it lives in the Java, Kotlin, or Groovy project.

When the code referenced from GitHub is exactly the same across projects, do not wrap it in <Tabs> + <TabItem> with separate GitHub references. Instead, inline the relevant code directly as a plain code block. Tabs that show identical content under different labels add click overhead with zero informational value.

Document Conclusions

Never end a document abruptly after the last code block or technical step. Every document should close with a conclusion that gives the reader a tangible sense of what was accomplished. Pick the most fitting format:

• A Mermaid sequence or flow diagram summarizing the flow just built (wrapped in <ZoomContainer><Mermaid .../></ZoomContainer>).
• A terminal curl command (or similar) that exercises the endpoint/feature just created, giving the reader a quick "try it now" moment.
• A brief closing paragraph stating what was achieved and what's next (e.g., "We now have a paginated films endpoint. Next, we'll add query parameters for filtering.").

Pick one format — don't pile all three. The conclusion should feel like a natural wrap-up, not a summary list.

Heading Capitalization

Use sentence case for all headings, not title case:

---
sidebar_position: 3