Skip to content

Chore(docs): Make the user docs easier to read - #194

Merged
Twest2 merged 5 commits into
mainfrom
docs/human-readable-cleanup
Nov 1, 2026
Merged

Twest2 merged 5 commits into
mainfrom
docs/human-readable-cleanup

Conversation

@Twest2

@Twest2 Twest2 commented Oct 31, 2026 •

Copy link
Copy Markdown
Owner

Cleans up the docs people actually read so they're easier to follow. No behavior changes. The technical details taken out of user docs move to ARCHITECTURE.md, so maintainers and AI agents still have them.

What changed

Fixes

  • README: the two "Share a guide" links pointed at a heading that doesn't exist (#share-a-guide-with-a-link). They now go to #share-a-guide-with-a-web-link.
  • Privacy and Security summaries only mentioned Google Drive and GitHub. They now list every optional online feature, including OneDrive, Dropbox, Nextcloud, Confluence and Wiki.js. Security also lists the Microsoft Store as a release channel.
  • Google Drive's "Settings that sync" (and the privacy policy) now include the interface language, which core/shared-settings.js syncs.

Less clutter

  • README: removed a sharing bullet that repeated the privacy check. The Install section now mentions the Store once, plus the badge.
  • Getting Started: replacing or retaking a screenshot gets its own short section instead of a ten-line bullet. The branding paragraph that listed every option now points to BRANDING.md. The Export, language, linked-guide and data folder notes are shorter.
  • AI agents: setup steps now come first. The lopsided can/can't table is now two plain lists. The undo section no longer covers internal details such as update_step and pruning.
  • Ollama AI: five overlapping bullets reduced to four short ones.
  • Wiki.js / Branding: shorter two-step-verification, annotation-color and agent notes.
  • Microsoft Store / Windows installer: the %APPDATA% move is explained in a few lines. The cleanup steps for the old folder are in a collapsed section.
  • Chocolatey: shorter Update and ".exe" sections. Silent-install switches move under For IT admins. The intro paragraph is unchanged.
  • Contributing: CI job internals move to ARCHITECTURE.md#tests-and-ci.

How to stop a recording

  • Getting Started has a new Stop recording section. The old wording ("the red StepForge icon in the system tray") was easy to miss: the icon is a plain red dot, not the StepForge logo, "system tray" isn't a term most people know, and Windows often hides the icon behind the ^ arrow.
  • Windows: the red dot beside the clock, how to find it behind ^, and what clicking and right-clicking do. As a fallback, opening StepForge from the Start menu also pauses recording and brings it back.
  • GNOME: ● StepForge REC → Stop recording, or the Stop recording button in the StepForge window.
  • It also notes that the click that stops recording is never a step, though clicks made while looking for the dot can be, and that Ctrl+Shift+2 pauses without bringing StepForge back.
  • The README quick start and the Linux guide now use the same wording, and Troubleshooting links to the section.

One page for every sync service

  • Google Drive came first, so GOOGLE_DRIVE.md was the page that explained how sync works. OneDrive, Dropbox and Nextcloud had a sign-in page that linked back to it.
  • CLOUD_ACCOUNTS.md is now Sync your guides between computers. It covers how sync works once for every service, then has a short section per service: Google Drive, OneDrive and Dropbox, and Nextcloud/WebDAV. The merge rules for synced settings are in plain language instead of spec detail.
  • GOOGLE_DRIVE.md is now a short pointer to the new page, so outside links keep working. Links inside the repo point to the new page.
  • Fixed: the docs and privacy policy said deleting a guide only deletes it on this computer. Since deletion sync (2026-09-21), a deleted guide moves to the Trash on your other computers, and one recovery copy is kept under Recently deleted.
  • Documented More → Guide information… → Include this guide in cloud sync, which keeps one guide on this computer only. Labels now match the app: Auto-sync, Guides in Drive, Replace OneDrive with this computer.

Moved to ARCHITECTURE.md: a new AI Agents (MCP) section (snapshot rules, blur-bypass protection, concurrent edits, brand tools), the settings-sync error rule, the one-hour grace period before unused parts are cleaned up, linked-guide lock behavior, and the CI layout.

Not changed

Checks

  • Every relative link and #anchor in the repo's Markdown resolves. Before this PR, the two README links above were broken.
  • license, packaging-linux and download-badges unit tests and test_repo_structure.sh pass.

Trim the user-facing guides down to what a reader needs: split long
bullets and paragraphs, drop internal edge cases, and point to the
detailed page instead of repeating it.

- README: fix the two broken "Share a guide" links, drop the bullet that
  repeated the privacy check, and simplify the Install section.
- Getting Started: give replacing/retaking a screenshot its own short
  section, and shorten the Export, language, linked-guide and data
  folder notes. Branding details now live only in BRANDING.md.
- AI agents: setup steps first, plain can/can't lists instead of a
  lopsided table, and a shorter undo section.
- Ollama AI, Google Drive, cloud accounts, Wiki.js, branding, Store,
  Chocolatey and Windows installer guides: shorter, plainer wording.
  Chocolatey's silent-install switches move under "For IT admins".
- Privacy and Security: the summaries now list every optional online
  feature (OneDrive, Dropbox, Nextcloud, Confluence, Wiki.js were
  missing), and Security lists the Microsoft Store as a release channel.
- Google Drive and Privacy: the interface language is listed as a synced
  setting, as it is in core/shared-settings.js.

Implementation details removed from user docs (agent snapshot rules,
blur-bypass protections, settings-sync merge rules, part clean-up grace
period, linked-guide lock behaviour, CI job layout) move to
ARCHITECTURE.md, so nothing is lost for maintainers and agents.
@Twest2 Twest2 changed the title Make the user docs easier to read Chore(docs): Make the user docs easier to read Oct 31, 2026
"Use the red StepForge icon in the system tray" was easy to miss: the
icon is a plain red dot rather than the StepForge logo, "system tray"
isn't a term most people know, and Windows often hides the icon behind
the ^ arrow.

Getting Started now has a "Stop recording" section: where the red dot
is on Windows (beside the clock, possibly behind ^), what clicking and
right-clicking it do, and reopening StepForge from the Start menu as a
fallback; and on GNOME, ● StepForge REC → Stop recording or the window's
own Stop recording button. It notes that the stopping click is never a
step but clicks made while searching can be, and that Ctrl+Shift+2
pauses without bringing StepForge back. The README quick start and the
Linux guide use the same wording, and Troubleshooting links to it.

Also close the comment in microsoft-store.md with --> (it ended with
-->>, which rendered a stray ">").
Google Drive was the first sync service, so GOOGLE_DRIVE.md became the
page that explained how sync works, and OneDrive, Dropbox and Nextcloud
got a sign-in page that linked back to it. A OneDrive user had to read
"Sync guides with Google Drive" to learn how their own sync worked.

CLOUD_ACCOUNTS.md is now "Sync your guides between computers": pick a
service, connect, everyday use, how changes are handled, settings that
sync, managing stored versions, limits, then a short section per service
(Google Drive, OneDrive and Dropbox, Nextcloud/WebDAV), disconnect,
privacy and troubleshooting. GOOGLE_DRIVE.md is a short pointer to it,
so outside links keep working. Internal links point to the new page.

While merging, matched the docs to the app:
- Deleting a synced guide deletes it on the other computers too (moved
  to their Trash, one recovery copy kept under Recently deleted). The
  docs and privacy policy said it only deleted it locally.
- Document More → Guide information… → "Include this guide in cloud
  sync" for keeping one guide local.
- The sync switch is labelled Auto-sync, and the indicator and buttons
  use the service's name (Guides in Drive, Replace OneDrive with this
  computer).
@Twest2
Twest2 merged commit 0271556 into main Nov 1, 2026
5 checks passed
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