From b0c45b7ccf275dae47dc5ce64f9c1d07ac15ef07 Mon Sep 17 00:00:00 2001 From: yaythomas Date: Tue, 12 May 2026 18:08:24 +0000 Subject: [PATCH] docs: expand authoring guide with writing style Previously authoring-guide.md was a Zensical formatting reference only. Expand it into a full authoring guide that covers both how to write well for this project and how to use Zensical features. New content: - Writing style rules (no emdash, no passive voice, no listicles, no marketing language) - SDK source verification requirement for code examples, with repo links and key source files per language - "Revise, Don't Append" rule to prevent stale or contradictory prose when editing existing pages - "Look Before You Write" rule to prevent duplicated or conflicting coverage across pages - Language neutrality rules (tab order, notes inside tabs) - Page structure template with exemplar pages - Pre-commit checklist Update CONTRIBUTING.md with both ways to run Zensical (activate venv or run the binary directly), a common commands list, and an "Adding New Pages" workflow. Update README.md to use "durable execution" consistently, add the Java SDK repo link, and simplify the authoring guide reference now that it covers writing style as well as formatting. --- CONTRIBUTING.md | 25 ++- README.md | 13 +- authoring-guide.md | 515 ++++++++++++++++++++++++++++++--------------- 3 files changed, 367 insertions(+), 186 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73b3fd3..aac78f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,19 +9,32 @@ python -m venv ~/.venvs/zensical source ~/.venvs/zensical/bin/activate pip install zensical ``` -### Preview site locally -Once installed, activate the venv and run Zensical from the repository root: +### Running Zensical + +Once installed, either activate the venv or run the binary directly: ```bash +# Option 1: Activate the venv source ~/.venvs/zensical/bin/activate - -# Live preview with hot-reload zensical serve -# Production build -zensical build --clean +# Option 2: Run directly without activating +~/.venvs/zensical/bin/zensical serve ``` +Common commands: + +- `zensical serve` — live preview with hot-reload +- `zensical build --clean` — production build +- Review build output for broken link warnings + +### Adding New Pages + +1. Create the markdown file in `docs/` +2. Add the page to the nav section in `zensical.toml` +3. Create corresponding code examples in all three languages under `examples/` +4. Test locally with `zensical serve` + ## Vendored dependencies The Zensical theme lazy-loads a few third-party assets (Mermaid for diagrams, diff --git a/README.md b/README.md index 551c432..42e749a 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,7 @@ -# AWS Lambda durable functions developer documentation source +# AWS Lambda durable execution developer documentation source This repository contains the source for the AWS Lambda Durable Execution SDK -documentation website at https://docs.aws.amazon.com/durable-execution, -providing comprehensive guides and references for building resilient, +documentation website at https://docs.aws.amazon.com/durable-execution, providing comprehensive guides and references for building resilient, long-running applications with AWS Lambda durable functions across multiple programming languages. @@ -40,10 +39,9 @@ pip install zensical zensical serve ``` -For the full authoring workflow — adding code samples, formatting conventions, -commit messages, and pull request process — see -[CONTRIBUTING.md](CONTRIBUTING.md). For Markdown formatting syntax, please see -the [Authoring Guide](authoring-guide.md). +For the full authoring workflow, please see [CONTRIBUTING.md](CONTRIBUTING.md). + +For writing style and Markdown formatting syntax, please see the [Authoring Guide](authoring-guide.md). ## Kiro Power @@ -64,6 +62,7 @@ for details. - [AWS Lambda durable functions Documentation](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html) - [JavaScript SDK Repository](https://github.com/aws/aws-durable-execution-sdk-js) - [Python SDK Repository](https://github.com/aws/aws-durable-execution-sdk-python) +- [Java SDK Repository](https://github.com/aws/aws-durable-execution-sdk-java) ## Feedback & Support diff --git a/authoring-guide.md b/authoring-guide.md index 200221c..c28758c 100644 --- a/authoring-guide.md +++ b/authoring-guide.md @@ -1,257 +1,426 @@ +# Authoring Guide -# Getting started +This guide covers how to author documentation for AWS Lambda Durable Functions. +For setup and contribution workflow, see [CONTRIBUTING.md](CONTRIBUTING.md). -For full documentation visit [zensical.org](https://zensical.org/docs/). +Each SDK reference page must be equally useful to TypeScript, Python, and Java +developers. No language is the implicit default. Language-specific quirks +belong inside the relevant tab, not in shared prose. -## Commands -* [`zensical serve`][serve] - Start local web server -* [`zensical build`][build] - Build your site +## Verify Against SDK Source - [serve]: https://zensical.org/docs/usage/preview/ - [build]: https://zensical.org/docs/usage/build/ +Before writing or updating any copy or examples, read the actual SDK source +for every language. Do not trust existing docs. Do not guess. Verify every +argument name, type, and return type against the source. -## Example formatting +Verify means: check each argument, each type of each argument and return, +find the definition for each of those types, and if those types reference +sub-types, find those too. Recurse until you have the full picture. -### Admonitions +For each code example: -> Go to [documentation](https://zensical.org/docs/authoring/admonitions/) +1. Find the method definition in the SDK source, not tests or docs +2. For each parameter, find its type definition. Recurse through nested types. +3. For Java, check both the sync and async variants (e.g. `step()` and `stepAsync()`) +4. Check the testing libraries of each repo for examples to verify your example code actually works -!!! note +### SDK repositories - This is a **note** admonition. Use it to provide helpful information. +You will need the SDK source for all three languages. Clone them alongside +the docs repo: -!!! warning +| Repository | Source path to read | +|---|---| +| [aws-durable-execution-sdk-js](https://github.com/aws/aws-durable-execution-sdk-js) | `packages/aws-durable-execution-sdk-js/src` | +| [aws-durable-execution-sdk-python](https://github.com/aws/aws-durable-execution-sdk-python) | `src/aws_durable_execution_sdk_python` | +| [aws-durable-execution-sdk-java](https://github.com/aws/aws-durable-execution-sdk-java) | `sdk/src/main/java/software/amazon/lambda/durable` | - This is a **warning** admonition. Be careful! +Testing SDKs are useful for confirming example code compiles and runs. The +JavaScript and Java testing SDKs live in the same repos as the main SDKs +(under `-testing` package paths). The Python testing SDK lives in a separate +repo: -### Details +| Repository | Source path to read | +|---|---| +| [aws-durable-execution-sdk-python-testing](https://github.com/aws/aws-durable-execution-sdk-python-testing) | `src/aws_durable_execution_sdk_python_testing` | -> Go to [documentation](https://zensical.org/docs/authoring/admonitions/#collapsible-blocks) -??? info "Click to expand for more info" - - This content is hidden until you click to expand it. - Great for FAQs or long explanations. +### Key source files -## Code Blocks +- **TypeScript**: `types/durable-context.ts` for `DurableContext`. Check + `types/step.ts`, `types/core.ts`, etc. for referenced types. +- **Python**: `context.py` for `DurableContext`. Check `config.py` for + `StepConfig` and `StepSemantics`. Check `types.py` for `StepContext`. +- **Java**: `DurableContext.java` for the interface. Check + `config/StepConfig.java`, `StepContext.java`, `StepSemantics.java`. -> Go to [documentation](https://zensical.org/docs/authoring/code-blocks/) +## Writing Style -``` python hl_lines="2" title="Code blocks" -def greet(name): - print(f"Hello, {name}!") # (1)! +### Voice and Tone + +Write for developers who want to learn how to use the SDK. Be direct and +technical. Avoid marketing language ("powerful", "flexible", "seamless"). + +Don't use unnecessary words. Keep sentences concise. + +Use active voice. Write "the SDK checkpoints the result" not "the result is +checkpointed". + +Every sentence must earn its place. If a sentence restates what the code +already shows, delete it. + +Per Strunk and White, use definite, specific, concrete language. Prefer +the specific to the general, the definite to the vague, the concrete to +the abstract. In practice, avoid 'to be' and 'to have' where you can use +stronger verbs. + +### Sentence Structure + +Do not use emdash (—) or hyphen as a dash. If you feel tempted to use one, +break it into two sentences or use a comma. + +Keep sentences short. One idea per sentence. -greet("Python") +### What to Avoid + +**Listicles.** Do not create Terminology, Key Features, Best Practices, or +FAQ sections. These are convenient for LLMs but not for humans learning to +code. If you feel tempted to write one, fold the content into prose: + +- New terms: introduce the term naturally in the prose where it first appears +- "Key features": drop them (usually marketing), or fold the underlying + capability into the relevant section +- Best practices: fold the guidance into the section where it applies. A + naming best practice belongs in the "Naming steps" section, not a generic + "Best Practices" list. +- FAQ Q&As: each question is either (a) a concept that belongs in prose, + (b) a code example that belongs in a code section, or (c) something + already covered elsewhere that doesn't need repeating + +**Navigation artifacts.** Do not add Table of Contents, "Back to top" links, +or "Back to X" links. Zensical generates navigation automatically. + +**Language-specific notes outside tabs.** Any note that applies to only one +language belongs inside that language's tab, not in shared prose. + +### List Items + +Do not use emdash or hyphen to separate a list item heading from its +description. Use bold or links instead: + +```markdown +- **StepConfig** configures retry behavior and timeouts +- [wait()](operations/wait.md) pauses execution for a duration ``` -1. > Go to [documentation](https://zensical.org/docs/authoring/code-blocks/#code-annotations) +## Revise, Don't Append - Code annotations allow to attach notes to lines of code. +When you update a page, revise the whole section. A fresh reader should not +have to reconcile an opening sentence with a later correction tacked on at +the end. -Code can also be highlighted inline: `#!python print("Hello, Python!")`. +If your new content qualifies, corrects, or extends something earlier on the +page, rewrite the earlier prose too. Don't leave stale sentences in place +because they were there first. -## Content tabs +Signs you are appending instead of revising: -> Go to [documentation](https://zensical.org/docs/authoring/content-tabs/) +- A new sentence at the end of a paragraph that qualifies an earlier one +- A "Note" or "Update" near the end of a section that contradicts the opening +- Two adjacent paragraphs making overlapping points +- A new code example below an older, now-redundant one -=== "Python" +When you spot one in your own edit, rewrite the section so the reader gets +a single, coherent story. + +## Look Before You Write + +Before writing a new page or section, search the docs for the topic. If +another page already covers it, add to that page instead of creating a +parallel explanation. Readers should get one canonical answer, not two +competing ones. + +If you find conflicting information on another page, fix both at once. Don't +leave a contradiction for the next reader to sort out. + +This applies equally to new pages and to edits on existing pages. A new +section on an existing page can duplicate content elsewhere just as easily +as a whole new page can. - ``` python - print("Hello from Python!") +## Language Neutrality + +Tab order is always: **TypeScript → Python → Java**. + +If a language has a quirk, note it inside that language's tab: + +```markdown +=== "TypeScript" + + Pass `undefined` as the name to omit it. + + ```typescript + --8<-- "examples/typescript/operations/steps/basic-step.ts" ``` -=== "Rust" +=== "Python" + + The `@durable_step` decorator uses the function name automatically. - ``` rs - println!("Hello from Rust!"); + ```python + --8<-- "examples/python/operations/steps/basic-step.py" ``` -## Diagrams +=== "Java" -> Go to [documentation](https://zensical.org/docs/authoring/diagrams/) + The name is always required. Pass `null` to omit it. -``` mermaid -graph LR - A[Start] --> B{Error?}; - B -->|Yes| C[Hmm...]; - C --> D[Debug]; - D --> B; - B ---->|No| E[Yay!]; + ```java + --8<-- "examples/java/operations/steps/basic-step.java" + ``` ``` -## Footnotes +## Page Structure -> Go to [documentation](https://zensical.org/docs/authoring/footnotes/) +SDK reference pages follow this pattern: -Here's a sentence with a footnote.[^1] +1. One or two short paragraphs explaining what the operation does and when + to use it +2. A minimal walkthrough example (tabs, all three languages) +3. Method signature section with per-language tabs +4. Parameters listed after the tabs (shared where identical, inside tabs + where language-specific) +5. Returns and Throws/Raises after parameters +6. Sub-sections for config types (StepConfig, StepContext, SemanticsEnum) + each with per-language tabs +7. Conceptual sub-sections as needed (naming, configuration, data passing, + nesting, concurrency) +8. "See also" at the end -Hover it, to see a tooltip. +### Exemplar pages -[^1]: This is the footnote. +Model tone and structure on these pages: +- [`wait.md`](docs/sdk-reference/operations/wait.md): simple method +- [`step.md`](docs/sdk-reference/operations/step.md): complex method with multiple types +- [`wait-for-condition.md`](docs/sdk-reference/operations/wait-for-condition.md): complex method with multiple types -## Formatting +### Template -> Go to [documentation](https://zensical.org/docs/authoring/formatting/) +```markdown +# {Operation Name} -- ==This was marked (highlight)== -- ^^This was inserted (underline)^^ -- ~~This was deleted (strikethrough)~~ -- H~2~O -- A^T^A -- ++ctrl+alt+del++ +## {Concept heading — what it does} -## Icons, Emojis +{One or two paragraphs. Language-neutral. No listicles.} -> Go to [documentation](https://zensical.org/docs/authoring/icons-emojis/) +{Simple walkthrough example with tabs} -* :sparkles: `:sparkles:` -* :rocket: `:rocket:` -* :tada: `:tada:` -* :memo: `:memo:` -* :eyes: `:eyes:` +## Method signature -## Maths +### {method name} -> Go to [documentation](https://zensical.org/docs/authoring/math/) +=== "TypeScript" + {signature} + **Parameters:** + - ... + **Returns:** ... + **Throws:** ... -$$ -\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k} -$$ +=== "Python" + {signature} + **Parameters:** + - ... + **Returns:** ... + **Raises:** ... -!!! warning "Needs configuration" - Note that MathJax is included via a `script` tag on this page and is not - configured in the generated default configuration to avoid including it - in a pages that do not need it. See the documentation for details on how - to configure it on all your pages if they are more Maths-heavy than these - simple starter pages. +=== "Java" + {sync and async signatures} + **Parameters:** + - ... + **Returns:** ... + **Throws:** ... - - +### {ConfigType} -## Task Lists +{same pattern — interface/dataclass/builder per tab} -> Go to [documentation](https://zensical.org/docs/authoring/lists/#using-task-lists) +### {ContextType} -* [x] Install Zensical -* [x] Configure `zensical.toml` -* [x] Write amazing documentation -* [ ] Deploy anywhere +### {SemanticsEnum} -## Tooltips +## The {operation}'s function -> Go to [documentation](https://zensical.org/docs/authoring/tooltips/) +### Anonymous {operation} functions -[Hover me][example] +### Pass arguments to the {operation} function - [example]: https://example.com "I'm a tooltip!" +## Naming {operations} +## Configuration -# basic markdown guide -# Markdown in 5min +## See also -## Headers -``` -# H1 Header -## H2 Header -### H3 Header -#### H4 Header -##### H5 Header -###### H6 Header +- [Related page](link) ``` -## Text formatting -``` -**bold text** -*italic text* -***bold and italic*** -~~strikethrough~~ -`inline code` -``` +## Code Examples + +### Requirements + +All code examples must: + +- Include all three languages (TypeScript, Python, Java) +- Be functionally equivalent across languages +- Include necessary imports +- Be minimal. Show the concept, not a full application. +- Avoid comments that restate what the code does +- Be verified against the actual SDK source before committing + +### File Organization -## Links and images ``` -[Link text](https://example.com) -[Link with title](https://example.com "Hover title") -![Alt text](image.jpg) -![Image with title](image.jpg "Image title") +examples/ + typescript/{section}/{subsection}/{example-name}.ts + python/{section}/{subsection}/{example-name}.py + java/{section}/{subsection}/{example-name}.java ``` -## Lists +Use hyphens in filenames. All three languages must have the same set of files. + +### Embedding in Docs + +Use the `--8<--` snippet syntax with content tabs: + +```markdown +=== "TypeScript" + + ```typescript + --8<-- "examples/typescript/operations/steps/basic-step.ts" + ``` + +=== "Python" + + ```python + --8<-- "examples/python/operations/steps/basic-step.py" + ``` + +=== "Java" + + ```java + --8<-- "examples/java/operations/steps/basic-step.java" + ``` ``` -Unordered: -- Item 1 -- Item 2 - - Nested item - -Ordered: -1. First item -2. Second item -3. Third item + +### Method Signatures + +Show the actual callable signature, not pseudocode. Use real types from the +SDK. + +For Java, show both sync and async variants: + +```markdown +=== "Java" + + ```java + // sync + T step(String name, Class resultType, Function func) + T step(String name, Class resultType, Function func, StepConfig config) + + // async + DurableFuture stepAsync(String name, Class resultType, Function func) + DurableFuture stepAsync(String name, Class resultType, Function func, StepConfig config) + ``` ``` -## Blockquotes +For TypeScript, show both overloads if they exist (e.g. named and unnamed). + +## Formatting Reference + +This project uses [Zensical](https://zensical.org) to build the documentation +site. + +### Admonitions + +```markdown +!!! note + + This is a note admonition. + +!!! warning + + This is a warning admonition. ``` -> This is a blockquote -> Multiple lines ->> Nested quote + +### Collapsible Blocks + +```markdown +??? info "Click to expand" + + Hidden content here. ``` -## Code blocks -```` -```javascript -function hello() { - console.log("Hello, world!"); -} +### Code Blocks + +````markdown +```python hl_lines="2" title="Example" +def greet(name): + print(f"Hello, {name}!") ``` ```` -## Tables -``` -| Header 1 | Header 2 | Header 3 | -|----------|----------|----------| -| Row 1 | Data | Data | -| Row 2 | Data | Data | -``` +Inline code with syntax highlighting: `` `#!python print("Hello")` `` -## Horizontal rule -``` ---- -or -*** -or -___ -``` +### Content Tabs -## Task lists -``` -- [x] Completed task -- [ ] Incomplete task -- [ ] Another task -``` +```markdown +=== "TypeScript" -## Escaping characters -``` -Use backslash to escape: \* \_ \# \` + ```typescript + console.log("Hello"); + ``` + +=== "Python" + + ```python + print("Hello") + ``` ``` -## Line breaks +### Diagrams + +````markdown +```mermaid +graph LR + A[Start] --> B{Error?}; + B -->|Yes| C[Retry]; + B -->|No| D[Done]; ``` -End a line with two spaces -to create a line break. +```` -Or use a blank line for a new paragraph. +### Tables + +```markdown +| Parameter | Type | Description | +|-----------|------|-------------| +| name | string | Step identifier | +| config | StepConfig | Optional configuration | ``` + +## Checklist Before Committing + +- [ ] All prose is language-neutral (no Python-only concepts described as universal) +- [ ] No Table of Contents, no "Back to top" links, no "Back to X" links +- [ ] No Terminology, Key Features, Best Practices, or FAQ sections +- [ ] Tab order is TypeScript → Python → Java everywhere +- [ ] Language-specific notes are inside tabs, not outside +- [ ] All three languages have example files for every `--8<--` reference +- [ ] 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 +- [ ] No emdash, no hyphen-as-dash +- [ ] No passive voice +- [ ] Updates are revisions, not tacked-on additions +- [ ] Topic is not already covered (or duplicated) on another page +- [ ] No contradictions with other pages +- [ ] Ran `~/.venvs/zensical/bin/mdformat docs/path/to/file.md` on the updated file +- [ ] Previewed with `~/.venvs/zensical/bin/zensical serve`