Phrasing, formatting, and link cleanups across docs#446
Open
cb341 wants to merge 7 commits into
Open
Conversation
cb341
force-pushed
the
feature/docs-phrasing
branch
2 times, most recently
from
7f16664 to
35c0308
Compare
cb341
force-pushed
the
feature/improve-docs
branch
from
9384c0e to
fd20e49
Compare
cb341
force-pushed
the
feature/docs-phrasing
branch
3 times, most recently
from
94353bd to
462f54e
Compare
cb341
force-pushed
the
feature/improve-docs
branch
from
f9fa4de to
de963c5
Compare
cb341
force-pushed
the
feature/improve-docs
branch
2 times, most recently
from
0ba3444 to
c3ebdb8
Compare
cb341
force-pushed
the
feature/docs-phrasing
branch
from
f994cfe to
d6ded0c
Compare
cb341
force-pushed
the
feature/improve-docs
branch
from
c3ebdb8 to
f9cea39
Compare
cb341
force-pushed
the
feature/docs-phrasing
branch
from
d6ded0c to
b2d9a41
Compare
cb341
force-pushed
the
feature/improve-docs
branch
from
f9cea39 to
39f7204
Compare
Restructure the docs so the guide reads as a single sequential walkthrough, and fold in the related content updates the restructure surfaced. Linearization (the spine of the change): - Top-level README: replace the single "Ruby on Rails" link with a four-phase "How to Use This Guide" roadmap; drop the outdated "Some Notes on the Side" intro, the "As an appendix" sentence, the "We want you to know..." line and the "Thank you" outro; reorder the "Do not blindly follow" and "challenge the guide" callouts up front; promote the basic-requirements bullet list to a "## What Needs to Be Ready" section. - SUMMARY: regroup pages under Before You Start / Rails Application Setup (Step 1–5) / Guides & Recipes / Services / Reference. Move `Create a GitHub Repository` into Step 1, split the Setup section into Step 1 (Create the App) and Step 2 (Deploy the App), add `AppSignal` to Step 4 and `Wallee Payment` / `Content Security Policy` / `I18n` to Guides & Recipes; move `Checklist`, `Go Live!` and the templates under Reference. - ruby_on_rails/README: insert `## Step 1: Create the App` … `## Step 5: Customer Plan Services` and `## Guides & Recipes` around the existing lists; switch the Guides & Recipes list from ordered to bulleted with an intro line that flags it as non-sequential; add a `> 💡 **Tip:**` block explaining the ✨ convention; insert `---` separators around Guides & Recipes; drop the dead `[README](compile_readme.md)` link and the redundant "Some services should be configured accordingly..." preamble. Content updates the linearization surfaced: - Drop the now-dead `ruby_on_rails/compile_readme.md` page. - Drop the broken `home_controller.rb` reference in cucumber.md that the RSpec template never shipped. - `first_git_push.md`: rewrite to acknowledge that `rails new` already creates the local git repo and initial commit; link back to the previous step instead of the file path. - `create_application_server_deploio.md`: shorten the "For further configuration" paragraph and surface the Rails guide first. - `configure_git_repository.md`: rewrite the Rules/Rulesets block around a `main` / `non-main` split (covers feature branches and long-living branches like `redesign`), reorder the Pull Requests checklist to match the GitHub UI, drop the trailing long-living-environment note (now redundant), drop the `(AFTER SETTING UP SEMAPHORE)` aside. - `create_git_repository.md`: rename the page title from "Create a Git Repository" to "Create a GitHub Repository" to match the new SUMMARY entry. - `linting_and_automatic_check.md`: add `> ✨` template-supplied markers to Renuocop and Brakeman, add a new Bundler-audit section, drop the now-redundant "It's already included in your Gemfile by default" line. - `rspec.md`: add a `> **Note:**` block clarifying that the Renuo Rails template does NOT set up RSpec. - `app_initialisation.md`: add `# may vary` comments on the example `time_zone` / `default_locale` values; switch the example `config.generators.apply_rubocop_autocorrect_after_generate!` line to the Rails 8 block form; rewrite the final "commit all your changes" bullet to "you're ready for the next step". No prose / formatting / emoji changes here — those live in feature/docs-phrasing and feature/emoji-cleanup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Linearize Application Setup Guide into sequential numbered steps - Refresh Bootstrap recipe and Wicked PDF instructions - Update README, SUMMARY, naming conventions - Various phrasing and formatting cleanups across guides - Update Gitlab hint, mdbook command examples - Add template-repo comments to Rails docs Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Convert every blockquote-style note/warning/tip/important into the GitHub `> [!XXX]` form so the docs render consistently: - `> **Note:**` / `> _Note_:` / `**Note:**` → `> [!NOTE]` - `>⚠️ ...` / `:warning:`-bracketed callouts → `> [!WARNING]` - `> :exclamation:` / `**:exclamation:` → `> [!IMPORTANT]` - `> :bulb:` → `> [!TIP]` - `> ⭐️` template-provided markers and `> ✨` Rails-default markers (semantically informational) → `> [!NOTE]` - `ℹ️ _..._` → `> [!NOTE]` Decorative emoji in headings, links, and celebratory inline lines (e.g. `:tada:`, `:fire:`, `:gem:`) are out of scope here and live in feature/emoji-cleanup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace decorative shortcodes (:tada:, :fire:, :cop:, :white_check_mark:, :bulb:, :gem:, :exclamation:, :warning:, :smile:, :mailbox:) with unicode emoji directly in source markdown. Drop the Emojify Book step from both GitHub Actions workflows since shortcode expansion is no longer needed. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Restructure the docs so the guide reads as a single sequential walkthrough, and fold in the related content updates the restructure surfaced. Linearization (the spine of the change): - Top-level README: replace the single "Ruby on Rails" link with a four-phase "How to Use This Guide" roadmap; drop the outdated "Some Notes on the Side" intro, the "As an appendix" sentence, the "We want you to know..." line and the "Thank you" outro; reorder the "Do not blindly follow" and "challenge the guide" callouts up front; promote the basic-requirements bullet list to a "## What Needs to Be Ready" section. - SUMMARY: regroup pages under Before You Start / Rails Application Setup (Step 1–5) / Guides & Recipes / Services / Reference. Move `Create a GitHub Repository` into Step 1, split the Setup section into Step 1 (Create the App) and Step 2 (Deploy the App), add `AppSignal` to Step 4 and `Wallee Payment` / `Content Security Policy` / `I18n` to Guides & Recipes; move `Checklist`, `Go Live!` and the templates under Reference. - ruby_on_rails/README: insert `## Step 1: Create the App` … `## Step 5: Customer Plan Services` and `## Guides & Recipes` around the existing lists; switch the Guides & Recipes list from ordered to bulleted with an intro line that flags it as non-sequential; add a `> 💡 **Tip:**` block explaining the ✨ convention; insert `---` separators around Guides & Recipes; drop the dead `[README](compile_readme.md)` link and the redundant "Some services should be configured accordingly..." preamble. Content updates the linearization surfaced: - Drop the now-dead `ruby_on_rails/compile_readme.md` page. - Drop the broken `home_controller.rb` reference in cucumber.md that the RSpec template never shipped. - `first_git_push.md`: rewrite to acknowledge that `rails new` already creates the local git repo and initial commit; link back to the previous step instead of the file path. - `create_application_server_deploio.md`: shorten the "For further configuration" paragraph and surface the Rails guide first. - `configure_git_repository.md`: rewrite the Rules/Rulesets block around a `main` / `non-main` split (covers feature branches and long-living branches like `redesign`), reorder the Pull Requests checklist to match the GitHub UI, drop the trailing long-living-environment note (now redundant), drop the `(AFTER SETTING UP SEMAPHORE)` aside. - `create_git_repository.md`: rename the page title from "Create a Git Repository" to "Create a GitHub Repository" to match the new SUMMARY entry. - `linting_and_automatic_check.md`: add `> ✨` template-supplied markers to Renuocop and Brakeman, add a new Bundler-audit section, drop the now-redundant "It's already included in your Gemfile by default" line. - `rspec.md`: add a `> **Note:**` block clarifying that the Renuo Rails template does NOT set up RSpec. - `app_initialisation.md`: add `# may vary` comments on the example `time_zone` / `default_locale` values; switch the example `config.generators.apply_rubocop_autocorrect_after_generate!` line to the Rails 8 block form; rewrite the final "commit all your changes" bullet to "you're ready for the next step". No prose / formatting / emoji changes here — those live in feature/docs-phrasing and feature/emoji-cleanup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Touch only the wording, callout syntax, and inline formatting in the guides — no structural / content changes (those live in the parent commit). On top of the original "normalize all callouts to GitHub-flavored alert syntax" pass, this also pulls in the smaller prose / formatting touch-ups that were previously mixed into the docs-restructure commit: - Convert remaining note / warning / tip / important callouts to the `> [!XXX]` form (incl. `:warning:`-bracketed, `> :bulb: **Tip:**`, `>⚠️ `, plain `**Note:**`, `> _Note_:`, `ℹ️ _..._`). - Wrap bare URLs in `<...>` or markdown links. - Replace `-->` arrows with `→`. - Capitalise product / language names that survived the restructure (`Bootstrap`, `Bullet`, `Lograge`, `Wicked PDF`, `JavaScript`, `GitHub`, `1Password`, ...). - Tighten prose without changing meaning: `set-up` → `set up`, `Convenience-scripts` → `Convenience scripts`, `bare` → `bear`, drop trailing emoji on warning lines, drop "(*CI*)" abbreviation, rephrase the README intro / outro paragraphs in ruby_on_rails/README.md, etc. - Backtick-wrap `[project-name]` / `.ruby-version` identifiers. - Replace inline 😊 with "happy" in the wallee sample spec. - Align the markdown table column widths in templates/README.md. - Inline the deploio command example as a fenced sh block. - Convert the suggested_libraries Tip / Important callouts. Decorative emoji shortcodes (`:tada:`, `:fire:`, `:gem:`, `:cop:`, `:white_check_mark:`, `:smile:`, `:mailbox:`, ...) are intentionally left untouched — they live in feature/emoji-cleanup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
cb341
force-pushed
the
feature/docs-phrasing
branch
from
b2d9a41 to
90f3b52
Compare
cb341
force-pushed
the
feature/improve-docs
branch
from
39f7204 to
6b618e6
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mechanical cleanups across the markdown sources: align table padding in the README template, fix the mbook→mdbook typo, convert bare URLs to auto-links, normalise note callouts to blockquoted Note: form, replace --> arrows with →, and add code formatting around [project-name] placeholders. Pin mdbook-version to 0.4.40 in CI to avoid drift from 'latest'.