docs: make the README an entry point, not a second reference manual - #19
Merged
Conversation
The README had grown to 466 lines that restated the documentation site in full: every entry point's lambda list, the reader callback semantics, the duplicate-key policies, the conversion helpers, the limits table, and the diagnostics readers. All of it already exists at nerima-lisp.github.io/cl-json-kit, maintained as the source of truth, so the copy was pure duplication -- and duplication that drifts is a real hazard now that 1.0 makes promises about behavior a stale README could contradict. Keep what a front page is for: what the library is, how to install it, one worked example, the mapping table people actually look up, the handful of properties that distinguish it, and links into the site for everything else. 115 lines. No content is lost; every removed section has a corresponding page linked from the new "What you also get" list.
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
1 participant
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 had grown to 466 lines that restated the documentation site in
full: every entry point's lambda list, the reader callback semantics, the
duplicate-key policies, the conversion helpers, the limits table, and the
diagnostics readers.
All of that already exists at https://nerima-lisp.github.io/cl-json-kit/,
maintained as the source of truth — so the README copy was pure duplication, and
duplication that drifts is a real hazard now that 1.0 makes promises about
behavior a stale README could contradict.
What the README keeps
people actually look up
conformance, the stability promise, bounded defaults, structured diagnostics,
Unicode correctness), each linking to its page
115 lines. No content is lost: every removed section has a corresponding
page linked from the new list.
Verification
Every retained example was evaluated against the built library; the referenced
documentation pages all exist and
mkdocs build --strictis clean.