Skip to content

docs: tighten the tone of the new tutorial pages - #61

Merged
wenh06 merged 4 commits into
masterfrom
docs-style-pass
Oct 29, 2026
Merged

wenh06 merged 4 commits into
masterfrom
docs-style-pass

Conversation

@wenh06

@wenh06 wenh06 commented Oct 28, 2026 •

Copy link
Copy Markdown
Owner

Summary

A language-style pass over the four tutorial pages already on master (quickstart, concepts, tutorial-first-experiment, tutorial-cli-matrix) plus test-files/quickstart.py:

  • Replace journalistic formulations with plain declarative sentences: "This page walks you through..." → "This page describes..."; "The accuracy story saturates; the communication story does not" → "Accuracy saturates on this task; the communication cost does not"; "The cast in one table" → "The four objects at a glance"; "the same communication budget buys two extra local iterations" → "at equal communication cost, FedPD performs two more local iterations"; "Two honest observations" → "Two observations"; "land on 180" → "both give 180"; "show up" → "appear"; "ships" → "provides"; "You will see" → declarative.
  • Use noun-phrase headings where the drafts had questions or imperatives: "Where do the logs go?" → "Log files"; "Run it" → "Running the matrix"; "Where the results land" → "Results location"; "drives the loop you will see below" → "drives the training loop described below".
  • Remove anthropomorphic phrasing: "without any of them knowing about each other" → "algorithms remain independent of the infrastructure"; "That invariant is what makes parallel runs trustworthy" → "This invariant underlies the reproducibility guarantees of parallel execution"; "A matrix of long experiments wants more than one process" → "...benefits from more than one process".
  • Reword the zh_CN translations to match, removing calques of the English constructions and aligning with the terminology of the existing translated pages.

Plus one CI fix:

  • docs-test-publish.yml: scope the concurrency group so that deploy-capable runs (pushes to doc/master, manual dispatch) share the pages-deploy lock while each pull request gets its own docs-build-<number> group. Previously every run shared one pages group with cancel-in-progress, so pull-request docs builds kept cancelling each other (and being cancelled by master deploys) even though PR builds never reach the publish step.

No technical content changes; all numbers, links and code blocks are unchanged.

Validation

  • English and zh_CN docs builds: zero warnings beyond the two pre-existing ones on master (intersphinx fetch flake, optimizers docstring).
  • Workflow file parses and the group expression evaluates to pages-deploy for deploy runs and docs-build-<number> for pull requests.

@codecov

codecov Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.79%. Comparing base (ca84c9b) to head (52a53f2).

Additional details and impacted files

Impacted file tree graph

@@           Coverage Diff           @@
##           master      #61   +/-   ##
=======================================
  Coverage   83.79%   83.79%           
=======================================
  Files          55       55           
  Lines        5640     5640           
=======================================
  Hits         4726     4726           
  Misses        914      914           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Align the phrasing with the rest of the documentation: replace
journalistic formulations ("walks you through", "the accuracy story",
"the cast in one table", "buys two extra iterations", "kept honest")
with plain declarative sentences, use noun-phrase headings where the
drafts had questions or imperatives, and reword the zh_CN translations
to match, removing calques of the English constructions (e.g. literal
"come back", "all you need"). No technical content changes.
The workflow-level 'pages' concurrency group applied to every run,
including pull-request builds that never reach the publish step. With
cancel-in-progress, any newer run in the group (another pull request's
docs build, or a deploy from master) cancelled older pending builds,
so two docs-touching pull requests kept cancelling each other's checks.

Deploy-capable runs (pushes to doc/master, manual dispatch) now share
the 'pages-deploy' group, keeping real page publications mutually
exclusive; each pull request gets its own 'docs-build-<number>' group.
@wenh06
wenh06 merged commit dead185 into master Oct 29, 2026
28 checks passed
@wenh06
wenh06 deleted the docs-style-pass branch October 29, 2026 18:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant