Repository navigation
Chore(docs): Make the user docs easier to read - #194
Merged
Merged
Conversation
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.
"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).
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
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.
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
#share-a-guide-with-a-link). They now go to#share-a-guide-with-a-web-link.core/shared-settings.jssyncs.Less clutter
BRANDING.md. The Export, language, linked-guide and data folder notes are shorter.update_stepand pruning.%APPDATA%move is explained in a few lines. The cleanup steps for the old folder are in a collapsed section.ARCHITECTURE.md#tests-and-ci.How to stop a recording
One page for every sync service
GOOGLE_DRIVE.mdwas the page that explained how sync works. OneDrive, Dropbox and Nextcloud had a sign-in page that linked back to it.CLOUD_ACCOUNTS.mdis 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.mdis now a short pointer to the new page, so outside links keep working. Links inside the repo point to the new page.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
BRANDING.md#advanced-css, etc.).GITHUB_PAGES.md,CONFLUENCE.md, the Linux guides and the BRANDING CSS reference tables. These were already clear or are reference material.Checks
#anchorin the repo's Markdown resolves. Before this PR, the two README links above were broken.license,packaging-linuxanddownload-badgesunit tests andtest_repo_structure.shpass.