Restructure README + SPEC#137
Merged
Merged
Conversation
adgad
force-pushed
the
restructure-docs
branch
from
2ce9595 to
9799e3f
Compare
Split into sections with clear headings, add some more context and background to project Fix a few typos here and there.
adgad
force-pushed
the
restructure-docs
branch
from
9799e3f to
6f55fab
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
2 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.
Problem
The README for this repository is currently a combination of documentation about the project, instructions for contributors, and the spec itself. This follows from the patterns used in unist specs, from which it was derived.
While it was neat to have the readme be the "one place" to look, it also had the counter effect of making the project less accessible to contributors or people wanting to know about the project. This would be exacerbated when we want to document some schema design principles/guidelines.
Solution
Split the content out into README.md and SPEC.md
The README contains:
The SPEC contains:
The schemas etc build in the same way, but they build from SPEC.md rather than README.md
What to review
Most of the changes exist in README.md (the SPEC is the same, just slightly re-ordered). It's probably best to read the README as a whole, rather than the diff.
In general, I want feedback on whether the changes make the project more accessible to newcomers, whilst still making the Spec easy to work with. It might not be perfect but hopefully a big step in the right direction!