-
Notifications
You must be signed in to change notification settings - Fork 349
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
readme: improved front matter, part 2 #2463
Conversation
6c63ed7
to
f79816b
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for improving this text. I like it.
I haven't read this super-carefully, but overall it looks really nice. Thank you! |
4a90845
to
b18364d
Compare
b18364d
to
6fc5256
Compare
FYI, I renamed the PR (inserted a space) because I kept misreading "frontmatter" as "formatter". A quick Google search seems to suggest that:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good, thank you!
I'm not sure whether @martinvonz wants to separately approve, but unless I missed something, most/all of the discussions seem resolved.
6fc5256
to
d170df2
Compare
I went ahead and gave it one more look over and fixed some typos and whatnot; let me know what you think. |
d170df2
to
4d386f2
Compare
4d386f2
to
b0ad75d
Compare
b0ad75d
to
3a2cd3e
Compare
3a2cd3e
to
1cc609f
Compare
1cc609f
to
d905820
Compare
Summary: What was going to just be some minor touch-ups to the existing content ended in another rework of the frontmatter, this time primarily the sales pitch and basic feature explanation. The motivation here is simple: you should not just encounter a three-word noun that is a hyperlink to pages with 1,000 words actually explaining the three-word noun itself is. It's jarring! Instead, the frontmatter is longer, expanding on each major selling point and similarity to other tools. It actually *describes* the important, distinct design decisions that tell you what the tool is and does, rather than just link you around a bunch. For example, one immediate thing is that calling jj a "DVCS" is actually kind of odd when it later becomes apparent that you can have multiple data model and commit backends; Google for example uses it in a more centralized manner than others would via Piper/CitC. Calling it a "DVCS" is a bit strange in this sense when *really* what we mean is that the Git data model allows independent copies of the repo. Overall I think this is *much* better for people who are just going to see the README and may or may not bounce off immediately. Signed-off-by: Austin Seipp <[email protected]> Change-Id: I9f0f78e56157ef434ec239710e00f3bd
d905820
to
52e361c
Compare
Summary: What was going to just be some minor touch-ups to the existing content ended in another rework of the frontmatter, this time primarily the sales pitch and basic feature explanation.
The motivation here is simple: you should not just encounter a three-word noun that is a hyperlink to pages with 1,000 words actually explaining the three-word noun itself is. It's jarring!
Instead, the frontmatter is longer, expanding on each major selling point and similarity to other tools. It actually describes the important, distinct design decisions that tell you what the tool is and does, rather than just link you around a bunch.
For example, one immediate thing is that calling jj a "DVCS" is actually kind of odd when it later becomes apparent that you can have multiple data model and commit backends; Google for example uses it in a more centralized manner than others would via Piper/CitC. Calling it a "DVCS" is a bit strange in this sense when really what we mean is that the Git data model allows independent copies of the repo.
Overall I think this is much better for people who are just going to see the README and may or may not bounce off immediately.
Change-Id: I9f0f78e56157ef434ec239710e00f3bd
Checklist
If applicable:
CHANGELOG.md