Skip to content

docs: style updates to custom-toolbox and validation-and-warnings codelabs - #10609

Merged
zspriggs merged 2 commits into
RaspberryPiFoundation:mainfrom
ritfiz:docs/codelab-style-toolbox-validation
Oct 22, 2026
Merged

zspriggs merged 2 commits into
RaspberryPiFoundation:mainfrom
ritfiz:docs/codelab-style-toolbox-validation

Conversation

@ritfiz

@ritfiz ritfiz commented Oct 22, 2026

Copy link
Copy Markdown
Contributor

The basics

The details

Resolves

Towards #10550

Proposed Changes

Updates the wording in the Custom Toolbox and Block Validation and Warnings codelabs to match the style used in the Getting Started codelab (#10575):

  • Instructions are written in the imperative, without "we", "let's", or "you will" (for example, "Finally, import the registration function" rather than "Finally, you'll need to import the registration function").
  • "You" is kept for observations that aren't instructions (for example, "If you open the running app, you should see a white gear...").
  • Functions are referred to as functionName rather than functionName().

Also fixes a few small issues found along the way in the Custom Toolbox codelab:

  • The "toolbox definition documentation" link in the overview had no URL.
  • The "screenreader support doc" link in the toolbox label step had a stray . between the text and the URL, so it didn't render as a link.
  • The "completed custom toolbox" link in the summary was missing tree/main/packages/ and pointed to a 404.
  • The "Change the category HTML" step said it would add an <img>, but the code adds a <span>. It now says it replaces the category's icon.

Code samples and code comments are unchanged, as are the "What you'll learn / build / need" headings.

Reason for Changes

Consistent, imperative instructions make the codelabs easier to follow, especially for developers who read English as a second language.

Test Coverage

Ran eslint on the changed .mdx files with no errors, and checked that the new link targets exist. Text-only changes, so no new tests.

Documentation

This PR is a documentation change.

Additional Information

This covers two of the codelabs, as suggested in #10550. The remaining codelabs can follow in separate PRs.

🤖 Generated with Claude Code

…elabs

Part of RaspberryPiFoundation#10550.

- Word instructions in the imperative, without "we", "let's", or
  "you will"; keep "you" for observations.
- Refer to functions without trailing parentheses.
- Fix broken links in the custom-toolbox overview, label step, and
  summary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ritfiz
ritfiz requested a review from a team as a code owner October 22, 2026 15:59
@ritfiz
ritfiz requested a review from mikeharv October 22, 2026 15:59
@github-actions github-actions Bot added the PR: docs Adds or updates documentation label Oct 22, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Welcome! It looks like this is your first pull request in Blockly, so here are a couple of tips:

  • You can find tips about contributing to Blockly and how to validate your changes on our developer site.
  • We use conventional commits to make versioning the package easier. Make sure your commit message is in the proper format or learn how to fix it.
  • If any of the other checks on this PR fail, you can click on them to learn why. It might be that your change caused a test failure, or that you need to double-check the style guide.
    Thank you for opening this PR! A member of the Blockly team will review it soon.

@ritfiz ritfiz mentioned this pull request Oct 22, 2026
1 of 3 tasks
@zspriggs
zspriggs self-requested a review October 22, 2026 16:39
@zspriggs
zspriggs removed the request for review from mikeharv October 22, 2026 16:39

@zspriggs zspriggs left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great! There's just a couple of sentences to rephrase, and then you should be good to go.

Comment thread packages/docs/docs/codelabs/custom-toolbox/adding-a-custom-toolbox-item.mdx Outdated
Comment thread packages/docs/docs/codelabs/validation-and-warnings/creating-the-block.mdx Outdated
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ritfiz
ritfiz requested a review from zspriggs October 22, 2026 17:21

@zspriggs zspriggs left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. Thanks again for the contribution!

@zspriggs
zspriggs merged commit 0708ecc into RaspberryPiFoundation:main Oct 22, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

PR: docs Adds or updates documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants