Workshop Docs Style

Workshop Documentation Style Guide

This guide captures the conventions established for the Quarkus LangChain4j workshop docs. It is self-contained for contributors to this repository; repeat a general writing rule here when workshop authors need it. The reference voice is Section 1, which was written by the project owner without AI assistance.

Voice and Tone

Write as a technical instructor talking to a developer sitting in front of their laptop. Be direct and practical. Avoid corporate enthusiasm ("Congratulations!", "Great!", "Easy right?") unless a brief one-liner fits naturally at the end of a section. Don't start pages with "In this step you will learn..." laundry lists.

Stay in the reader's exercise

Keep learner-facing prose about the business scenario, system behavior, and actions the reader can take. Do not insert workshop-author commentary about how chapters are being built, what is planned or omitted, or which features have not been implemented. For example, delete asides such as "The section will build toward checking offers with external services, but the current planner has no extras catalog or reservation service." Keep roadmap and implementation-status details in planning documents. An unfinished chapter can retain one short "Coming soon" notice without repeating that status throughout its prose.

Do not narrate our local testing history or conversations with the project owner. Dates, model-specific outcomes, run identifiers, incidental screenshot details, and accounts of what worked during author testing belong in maintenance notes, not the tutorial. Explain what the reader should inspect and why. Preserve setup instructions and limitations that affect the exercise, such as a simulated booking, state lost on restart, or a price covering vehicle rental only. Put these beside the relevant action instead of adding general disclaimers to the scenario.

Connected prose

Concise does not mean a succession of short, abrupt sentences. Develop each paragraph around a connected idea, using cause, contrast, or sequence to help one sentence lead into the next. Vary sentence length naturally, without turning every explanation into either clipped statements or one long sentence.

• Avoid: The application restarts. The plan is lost. The customer starts again. We need persistence.
• Prefer: If the application restarts while the customer is reading their itinerary, the plan disappears and they have to generate it again. Saving the pending trip allows them to return to the same plan and continue with approval.

Avoid joining explanatory clauses with a semicolon. Express the relationship naturally with wording such as even with, although, or because, or reshape the surrounding sentences. Do not simply replace every semicolon with a period, which can leave the same abrupt rhythm. This applies to prose, not syntax in code or quoted output.

• Avoid: The skills added in Step 01 guide the agents' choices; they cannot ensure that every response follows those instructions.
• Prefer: Even with the skills we added in Step 01, the agents can still overlook our instructions when generating a response. The application therefore needs checks of its own before passing recommendations to the rest of the planning pipeline.

Read the prose aloud before finishing. If it sounds like a list with the bullets removed, reconnect the ideas rather than just adding transition words. Short action directives are fine, while explanatory paragraphs should have a more conversational rhythm.

When connecting lessons, explain why the previous capability leaves a problem for this chapter to solve. Repeating that the agents now have data does not explain why they might misuse it.

• Avoid: In Step 06, we gave the planner weather forecasts through MCP. The agents now have that information available, but they can still overlook something the customer asked for.
• Prefer: In Step 06, we connected the planner to weather tools through MCP so it could use their forecasts when recommending a trip. Even with those details, the model still has to choose activities that fit the customer's request.

AI Style Tells to Avoid

These patterns are strong signals that text was generated by an AI. Actively avoid them:

The em-dash clarification pattern. Do not write X — it does Y or X — Y, Z, and W. Instead, write it as a full sentence or clause.

• Bad: The @Output method assembles the final TripPlan from scope values — pure Java, no extra LLM call.
• Good: The @Output method assembles the final TripPlan from scope values using pure Java without an extra LLM call.
• Also bad: The left panel is the trip form — destination, duration, number of travelers.
• Good: The left panel is the trip form with fields for destination, duration, and number of travelers.

Generic recaps after code. Avoid "Key Points" or "Key Takeaways" lists that repeat the snippet or make broad claims about its benefits. Use "What to notice" selectively for complex changes, as described under Code Block Explanations.

The feature-benefit bullet list. Avoid lists of the form:

- **Hot-reload friendly**: Quarkus dev mode picks up changes automatically
- **Separation of concerns**: Domain experts can author skill content in Markdown

Write the same content as a paragraph instead.

Bold label: explanation inline. Avoid **Feature**: description patterns in running text. Use prose.

Colon-separated label/description lists in prose. Do not write The left panel renders: vehicle recommendation, route overview, daily itinerary. Write it as a sentence: The left panel renders the vehicle recommendation, route overview, and daily itinerary.

The sentence-then-colon explanation pattern. Avoid setups like For this step, the flow is simple: or The workflow does one thing: followed by an explanation. This sounds synthetic even when the content is correct. Write it as normal prose instead.

• Bad: For this step, the flow is simple: start from an event, wait for approval, then continue.
• Better: The flow starts from an event, waits for approval, and then continues.

Vague framing around behavior. Avoid empty scaffolding phrases such as it does one simple thing, the flow is simple, or you start from. Name the behavior directly.

• Bad: The workflow does one simple thing.
• Better: The workflow takes a booking event, generates a trip plan, and waits for approval.

Mechanical walkthrough voice for explanations. Describe system behavior with the system as the subject, rather than pretending the reader performs its internal operations. Direct address is still welcome when connecting lessons or guiding the exercise: You've seen how system and user prompts work, We're going to add four skills, or In the tests we just did.... These transitions should refer to actual prior work and explain why the next activity follows. Reserve ==highlighted text== for actions to perform now, not every use of you or we.

• Bad: You start from an event with schedule and then wait with listen.
• Better: The workflow starts from an event with schedule and then waits with listen.

"That" as a sentence opener. AI models frequently start follow-up sentences with "That works...", "That means...", "That way...". Use "This" instead, which sounds more natural in written English.

• Bad: The request comes in and the agents run. That works for immediate answers.
• Better: The request comes in and the agents run. This works for immediate answers.

Explain behavior first, API names second. When introducing workflow steps, standards, or architecture, start with what happens in plain language. Then tie it back to the concrete API names or annotations.

• Better: The workflow waits for the approval response before continuing. In the code, that pause is handled by listen().

Keep exact filenames, method names, and variables where the reader needs them to locate or edit code. In the surrounding explanation, describe the behavior without repeating every identifier. Explain why the change is needed instead of translating the code into prose.

Introduce details where the reader will use them. Explain the purpose of a skill before its directory layout, then define YAML frontmatter briefly when asking the reader to create the file. Familiarity with earlier workshop concepts does not imply familiarity with every supporting format. Put reference links beside the relevant explanation; the reader should not need to leave the tutorial to understand a required edit.

• Avoid: handleApprovalRequested() writes planJson and sets status to awaiting_approval. handleBookingFinalized() updates confirmationJson.
• Prefer: When the plan is ready for approval, the store saves it together with the original request. Once booking finishes, it adds the confirmation to the same record, so the browser can retrieve the outcome after a restart.

Preemptive reassurance. Do not add sentences that address a concern the reader hasn't raised, such as "The tests do not call a live model", "No external services are required", or "This will not affect your existing configuration." If something genuinely requires a prerequisite or has a limitation, state it as a concrete instruction beside the relevant action. A floating reassurance in isolation adds noise without helping anyone complete the exercise.

Parallel bullet structure that sounds like a spec. Instead of:

- `CostEstimatorAgent` reads vehicle and itineraryResult from scope
- outputKey = "costs"
- No skills needed

Explain the behavior introduced by a method or annotation in connected prose. Use short, complete bullets when several independent points are easier to scan as a list.

Metaphor as shorthand for a concrete explanation. Avoid vague figurative phrases like "different lenses", "wearing different hats", or "from different angles" when describing what agents or components do. These are unclear to non-native speakers and substitute a metaphor for the actual explanation. Name what the agent or component specifically does instead.

• Bad: Each evaluator approaches the vehicle from a different angle.
• Good: Each evaluator is given a single concern — comfort, cost, or fuel efficiency — and scores the vehicle against that concern only.

When Lists Are Fine

Bullet lists are appropriate for:

• Form field values the reader is instructed to type (destination, duration, etc.)
• Prerequisite lists
• Troubleshooting steps where each item is a discrete check
• Sequential commands where order matters
• Focused "What to notice" lists for complex changes with several independent ideas

MkDocs Admonitions

!!!tip, !!!note, !!!warning, and ???warning (collapsible) are all fine and encouraged where they add value. Use !!!tip for helpful shortcuts or alternative approaches. Use !!!note for important context that isn't a warning. Use ???warning (collapsible) for troubleshooting blocks so they don't clutter the page. Do not invent a reason to add an admonition on every page — use them only when the content genuinely benefits from the callout treatment.

Use ??? info "Why not ...?" for optional design discussions, alternative approaches, or deeper implementation details. These boxes must be closed by default, so use ???, not ???+. Indent all of the explanation inside the box.

A short recap of the supplied starter can use a visible !!! info box with a small diagram. This separates existing behavior from the new work without hiding useful orientation. Use a collapsed box when the recap becomes a deeper implementation discussion.

Keep required edits and safety-critical instructions visible. If an implementation limitation affects the exercise, state the practical instruction in the main text and put the deeper explanation in a collapsed box. Readers should be able to complete the chapter without opening optional background sections.

Action Directives

Use ==highlighted text== whenever the reader is supposed to do something right now: open a file, type a value, run a command, click a button. This is a MkDocs highlight and renders as a yellow marker.

Examples:

• ==Open application.properties and add the following:==
• ==Navigate to section-3/step-01 and start the application:==
• ==Click **Generate Trip Plan**.==

Do not use action directives for passive observations ("Notice how...").

Optional practice suggestions can stay in ordinary prose when clearly introduced as optional. If an optional exercise includes a worked sequence, mark its immediate actions just like the main exercise.

Code Block Explanations

Explain why a file or change is needed before the highlighted action directive and code. Afterward, default to a short, connected paragraph about the new behavior. Related snippets, such as adding the same annotation to two agents, can share one explanation after both blocks.

After a code block, if the change has several independent ideas worth calling out, use a short bullet list. Do not add a "What to notice" heading above it — just start the bullets directly. Reserve the list for genuinely independent points that are easier to scan than to connect in prose. Small annotation changes, simple helpers, and most test excerpts need only a paragraph, not a list at all.

When walking through several distinct annotations or methods in a class — for example explaining @LoopAgent, maxIterations, @ExitCondition, and an output key each doing different things — use bullets, one per item. Do not collapse these into a dense paragraph. A paragraph is appropriate when the points are causally connected; bullets are appropriate when each item stands alone.

When using the list, tie each short bullet to a relevant method, annotation, or assertion. Focus on behavior the reader could miss. Do not list every field and method just to fill the pattern, and do not repeat what the preceding prose already said.

For example, a guardrail whose validate() runs independent checks in order reads better as a lead sentence and one bullet per check, followed by a short paragraph for the shared consequence:

`validate()` runs three checks in order and returns as soon as one fails:

- The response must parse as JSON. `extractJson()` strips any Markdown fences the model wraps around it.
- The `itinerary` array must contain at least one day.
- The route overview and day descriptions must not contain any phrase from `DANGEROUS_KEYWORDS`.

A failed check returns `retry()`, which asks the model for a new response.

By contrast, adding @OutputGuardrails to two agents needs one paragraph, not a list.

Add a compact input or output example when it clarifies the behavior, and label illustrative output clearly. Preserve limitations that affect the exercise beside the relevant code. Avoid repeating the explanation in a closing summary or adding a transition that merely announces the next heading.

Review the page as a whole for rhythm and repetition. Alternate prose and lists according to the material, without turning short bullets into a dense paragraph or imposing a fixed number of lists per chapter.

Updating existing code

For files that already exist in the previous step, tell the reader to update the highlighted lines rather than replace the entire file. Use MkDocs hl_lines to distinguish additions and changes from unchanged context, and explicitly identify fields or imports that must be removed, since they will not appear in the resulting snippet.

Split long classes into focused excerpts at useful editing boundaries, keeping every required change visible. A collapsed "Complete updated file" box can provide the full class for comparison. New, short files can be shown in full without breaking them into excerpts.

Prefer the repository's source includes (--8<--) so snippets match the completed step. For excerpts, use the supported path:start:end syntax and check that hl_lines counts from the beginning of the excerpt, not the original file. Recheck ranges and highlights whenever the source changes, and make it clear when an excerpt shows only a method declaration whose body should stay unchanged.

When a chapter adds several settings to the same properties file, give the reader one clear edit at the point where the settings are needed. If later text refers to a setting already shown, explain its purpose there without instructing the reader to add it again. Check that each properties snippet renders the intended lines in MkDocs.

Section Structure

Opening the chapter

Every chapter should open as a continuation of the previous step, including the first chapter of a new section. Connect what the reader just built or learned to the next concrete problem in the customer journey, then explain what this chapter will change and what the reader will learn through making that change. Preview an observable result they will verify at the end, such as approving the same trip after an application restart.

Make the connection to the previous step once, then explain the new capability on its own terms. Repeated "in Step 04" comparisons make readers reconstruct the earlier lesson instead of understanding the current one. When revising a later section at the author's request, preserve the opening unless the request includes it or a specific inconsistency requires a change.

At the start of a new section or application scenario, make that connection before introducing the new application. Explain how the previous step's outcome or patterns lead into the next customer need, without inventing a code dependency between separate applications. A prerequisite reminder alone is not that connection. Then introduce what the customer needs and what the application returns. An early screenshot gives readers a concrete view of what they will run. Explain what the starter already does, what it lacks, and what this chapter adds before discussing its internal orchestration.

Give these ideas a clear progression in flowing paragraphs rather than separate "What / Why / Learning objectives" inventories. Headings such as "A new scenario" and "What are we building?" are useful when they answer distinct reader questions. Introduce product names when useful, but leave class names and configuration properties for the implementation. A defining mechanism, such as activate_skill, can appear earlier if it makes the new concept concrete; do not turn the opening into an API inventory.

When a chapter introduces an unfamiliar practice such as evaluation, explain what the practice is and why the reader needs it before using the trip scenario to illustrate it. Then introduce the service or extension that supports the practice. Do not begin with the sample file, a check written in Java, or a workflow class and expect the reader to infer the larger purpose.

• Avoid: The itinerary must have three days, which Java can check exactly. as the first explanation of evaluation.
• Prefer: Evaluation checks a generated plan against a saved request and its requirements, so we can compare results after changing the planner. Then show how the three-day Rome request makes that idea concrete.

When introducing two mechanisms that look similar, explain who decides when each runs and what result it changes. For @McpToolBox and @McpClientAgent, explain model-selected tool use versus a workflow-invoked agent before naming the workshop class that uses either mechanism. For a runtime judge and a Langfuse evaluation judge, explain that one can request a retry during planning while the other scores a finished plan.