Skip to content

docs: add authoring rules for single-language integration pages #288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nvasiu merged 1 commit into from
Sep 9, 2026
+18 −1
Merged

docs: add authoring rules for single-language integration pages #288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ Edit documentation in the markdown files under `docs/`.

Embed code samples in documentation pages with the `--8<--` snippet syntax with content tabs for multi-language support.

**IMPORTANT**: All code examples MUST include all four languages (TypeScript, Python, Java, C#) and remain functionally equivalent across languages. The tab order must always be TypeScript → Python → Java → C#.
**IMPORTANT**: All code examples MUST include all four languages (TypeScript, Python, Java, C#) and remain functionally equivalent across languages. The tab order must always be TypeScript → Python → Java → C#. Single-language integration pages are the exception.

#### Steps to add a new code sample:

Expand Down
17 changes: 17 additions & 0 deletions authoring-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,22 @@ If a language has a quirk, note it inside that language's tab:
```
```

## Integration Pages

An integration page documents a third-party framework that works with the
Durable Execution SDK. Integration pages live under
`docs/sdk-reference/integrations/`. Some frameworks exist in one language.
Pydantic AI is Python only.

For a single-language integration, the four-language rules do not apply. State
the framework's language in the first sentence. Write the rest of the page in
that language alone. Use a plain code fence instead of content tabs, because
tabs separate languages and this page has only one.

Everything else still applies. Keep the example minimal, store it under
`examples/{language}/`, embed it with `--8<--`, and verify it against the
framework and the SDK source before committing.

## Page Structure

SDK reference pages follow this pattern:
Expand Down Expand Up @@ -374,6 +390,7 @@ grammar. The items below cover authoring mechanics.
- [ ] Tab order is TypeScript → Python → Java → C# everywhere
- [ ] Language-specific notes are inside tabs, not outside
- [ ] All four languages have example files for every `--8<--` reference
- [ ] Single-language integration pages use one language and a plain code fence instead of tabs
- [ ] Every example verified against the actual SDK source
- [ ] Java method signatures show both sync and async variants
- [ ] TypeScript signatures show both overloads where they exist
Expand Down
Loading