workshop-docs-style

# Workshop Documentation Style Guide This guide captures the conventions established for the Quarkus LangChain4j workshop docs. 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. ## 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, the audit logger needs only: "Calling `log()` writes the guardrail's name, decision, and reason to the terminal. It also keeps the latest 100 entries in memory for tests to inspect through `getRecentEntries()`, until the application restarts." 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. ## 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. 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. ### Choosing a starting point When starter and completed projects are available, provide clearly labeled MkDocs tabs for building hands-on or reviewing the completed solution. Explain that the solution is also a comparison point if a participant gets stuck. Identify the working directory for each route and where the routes rejoin for running and testing, so reviewers do not repeat edits already present in their project. Keep prerequisites such as API keys visible for both routes and use platform tabs where commands differ. ### Introducing a pattern When a heading introduces an architectural or agentic pattern — voting, loops, adaptive model selection, or similar — the opening prose must do two things. First, explain what the pattern does mechanically. Then follow with a separate sentence or short paragraph explaining why you would reach for it in a real production system: what problem it solves that simpler approaches cannot, or what property it gives the system that matters at scale. This second part must stay at the level of the pattern itself, not the workshop scenario. It should be true regardless of whether the system is recommending cars, reviewing documents, or pricing insurance claims. If you find yourself writing about vehicles, trip types, or budget tiers in the "why it matters" sentence, you have drifted back into the scenario. Rewrite it in general terms. - Bad: `Using three evaluators means a vehicle that scores 9 on comfort but 4 on cost still gets caught.` - Good: `Distributing evaluation across narrowly-scoped agents means no single concern can be silently traded away against another during aggregation.` Also avoid explaining the pattern's value by restating how it works. The "why" should add something the mechanical description does not already cover. - Bad: `The loop keeps running until the score reaches the threshold, which ensures the output meets the standard.` - Good: `A numeric score and an explicit exit condition make quality verifiable — you can write a test that asserts the system meets a defined standard rather than relying on manual review.` ### Organizing the exercise Avoid artificial numbering within a page ("Step 1", "Part 2"). Use descriptive headings. The MkDocs table of contents provides navigation structure already. Use imperative verb forms for headings that describe an action the reader takes: "Create the evaluator agents", "Configure adaptive model selection", "Update the main workflow". Reserve noun or gerund forms for conceptual or navigational sections that describe a topic rather than a task: "Parallel assessment with the Voting pattern", "Troubleshooting", "What's next?". Prefer headings that describe what the work accomplishes, such as "Saving workflow progress" or "Showing the restored trip", over a series of generic "Dependencies", "Configuration", and "Implementation" sections. Keep setup details near the work they enable, and avoid repeating the same overview in requirements, objectives, and architecture sections. Use Section 1 for explanation pacing and the concrete business scenarios in Section 2 for motivation. Do not copy earlier chapters' identifier-heavy objective lists or generic recap blocks just because they already exist. Use the focused file-change explanations described above. Section 3 step 01 is a reference for introducing a new scenario, offering participation routes, and teaching execution inspection. Step 04 is a reference for focused edits and optional background. Neither is a fixed template for every chapter. Keep the required path focused on implementing and verifying the chapter's new concept. Remove unrelated UI tours or refinement exercises. Once the core behavior has been checked, a short "Taking it further" section can invite readers to apply the pattern themselves, such as adding another skill or changing access restrictions. Give a concrete experiment and something to inspect without supplying another complete copy-paste solution. Keep optional changes out of the baseline assumed by the next chapter. Do not add a "Cleanup" section merely to tell readers to press Ctrl+C. Explain cleanup when it has consequences they need to understand, such as deleting the reused database and its saved trips. ## Diagrams and screenshots When planning or revising a chapter, look for places where a Mermaid diagram or screenshot would make the explanation easier to understand. Use diagrams for relationships and sequences, and screenshots for what the reader should recognize in the running application. Include both when they answer different questions, without treating visuals as decoration or requiring a fixed number per chapter. Add a diagram when it answers a question that is harder to explain in prose, such as which component owns each kind of state or what survives an application restart. Place it beside that concept and trim the surrounding explanation so the reader does not work through the same account twice. Use plain-language labels before introducing code identifiers. Keep diagrams small enough to read on mobile, and distinguish relationships in a flowchart from the order of events in a sequence diagram. Two diagrams should answer different questions; there is no need to add one to every chapter. Validate Mermaid diagrams with a Mermaid renderer, not just a documentation build. MkDocs can build successfully while leaving invalid Mermaid for the browser to reject. When available, run `mmdc -i <chapter.md> -o <temporary-output.md>` to render the chapter's diagrams outside the source tree. Avoid literal semicolons in sequence-diagram messages or notes because Mermaid treats them as statement separators; use a line break or reword the label. Distinguish syntax/rendering checks from checking the actual page layout in a browser. Screenshots are useful for introducing the application, unfamiliar Dev UI navigation, an important application state, or a result that confirms the exercise worked. Place each capture beside the relevant instruction or observation, crop it to the useful area, and provide descriptive alt text. Refer back to an early application screenshot instead of repeating it when the reader starts testing. Keep essential instructions in prose so readers do not have to extract them from an image. For unfamiliar inspection tools, give the actual navigation path: a clickable URL, the named card or menu, the action to select, and the run or detail to expand. Pair navigation and result screenshots with their respective instructions. A supported keyboard shortcut can help, but should not replace the visible navigation route. Capture the actual application and check existing screenshots against the current behavior before reusing them. Do not fabricate screens, logs, or successful outcomes. Remove secrets and personal information, store captures with the workshop's existing image assets, and ensure important text remains readable on a small screen. If a capture cannot be obtained or verified, report that gap rather than presenting an assumed result as evidence. ## Teaching verification After readers try the feature, connect the inspection exercise to a question the visible result cannot answer. A plausible itinerary does not prove a skill was activated. Explain this at the transition into inspection instead of repeating the same caveat after every test case. Keep warnings that affect an edit beside that edit. Teach readers to recognize evidence, not merely to open a log. In the skills example, startup discovery confirms files were found; an outgoing tool definition confirms availability; a response's `tool_calls` entry shows the model requested activation; and the subsequent tool message shows the returned content. Show short, relevant excerpts and identify which request or response contains each one. Do not imply that activation alone proves the model followed every instruction in the skill. Use short log excerpts only when they help the reader recognize a specific interaction. Explain what a tool call, error, or returned result means without recounting the author's run. Distinguish illustrative excerpts and fixed-response test output from guarantees about live-model behavior. For recoverable errors, explain how to check for a later successful result without promising recovery. Do not turn generated recommendations or timings from local testing into expected outcomes for the reader. ## Final review Read the chapter once as an explanation and once as an exercise. The first pass should make sense without decoding every identifier; the second should supply all edits needed to continue from the previous step. Check source includes and highlighted lines, build with `pipenv run mkdocs build --clean` from `docs/`, and separately render any changed Mermaid diagrams. Verify screenshot paths, relevance, and readability, and check that the visuals explain something the prose alone makes difficult. Report validation gaps instead of assuming a successful build proves the page renders correctly. Check each participation route separately, including its prerequisites and the point where it joins the shared exercise. Confirm that verification shows evidence of the behavior being taught, and that skipping optional practice leaves the reader ready for the next chapter. ## "What's Next?" Endings End pages with a short paragraph summarising what was learned (1–2 sentences, no bullet recap) and a plain sentence introducing the next step. No exclamation marks. Example: ``` The customer can now return to a pending trip after an application restart, but the decision is still limited to approving or rejecting the plan. In Step 05, we'll explore how evaluator agents can review a plan and request another pass when it needs improvement, using voting and refinement loops. ```