Repository navigation
docs: split the README into docs/, and document the dashboard - #52
Merged
Merged
Conversation
The README had grown to 527 lines, of which 133 were changelog and most of the rest was reference material. Anyone arriving at the repository had to scroll past every setting to find out what the thing was. It is now 123 lines: what it does, how to start, where the documentation is, and why it exists. The reference moves to docs/, a page per subject, and the changelog to CHANGELOG.md where tooling expects it. The dashboard had no documentation at all, having been written after the last README pass. docs/dashboard.md covers the generated password and why it goes to the console rather than the log, choosing your own, what the page shows, and that authentication deliberately does not cover the endpoints Plex calls. Every internal link and anchor was checked after the split, including the ones that used to be same-page anchors and are now cross-file.
The rule exists to keep local security notes out of the repository, but it was not anchored, so it matched at any depth and, on a case insensitive filesystem, matched docs/security.md too. The page was silently left untracked and the link to it from the README would have been a 404 on GitHub. Anchored to the root. The local notes are still ignored.
The prose was wrapped at roughly 78 columns, which markdown ignores when it renders but which makes the source annoying to edit: changing a word reflows the paragraph. Paragraphs are now one line each. Fenced blocks, lists and tables keep the line breaks they need, and the changelog keeps its wrapping because it lives inside a fence. The pages I wrote also read like documentation written by committee, which is to say every sentence explained itself. The dashboard page and the several providers section are rewritten to sound like someone telling you how the thing works. Your original text is left as it was.
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.
The README was 527 lines, 133 of them changelog. Anyone arriving at the repo had to scroll past every setting to find out what the thing was.
Now 123 lines: what it does, how to start, where the docs are, why it exists.
Reference material moves to
docs/, a page per subject, and the changelog toCHANGELOG.md.The dashboard had no documentation at all, having been written after the last README pass.
docs/dashboard.mdcovers the generated password and why it goes to the console rather than the log, setting your own, what the page shows, and that auth deliberately does not cover the endpoints Plex calls.Two things worth flagging:
docs/security.mdwas silently untracked. TheSECURITY.mdignore rule for your local notes was not root-anchored, so it matched at any depth and, on a case-insensitive filesystem, matcheddocs/security.mdtoo. The README link to it would have 404'd on GitHub. Now anchored; the local notes are still ignored.