-
-
Notifications
You must be signed in to change notification settings - Fork 6.7k
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
Make certain usage patterns more prominent in the README #3557
Merged
Conversation
This file contains 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
We use this library extensively where I work. After pairing with many teammates, I've learned that one common stumbling point when using this library is how to first get a JSON value in the first place (because once they have a variable of type `json` in hand, the API is intuitive and mostly does what you expect). With that in mind, I've added two subsections to the top of the Examples section: how to read JSON from a file, and how to hardcode a JSON literal. I understand that these are already documented elsewhere in the Examples section, and so these new subsections are technically redundant. But to defend this choice: - Redundancy in docs is actually good, because not everyone consumes docs in the same way or in the same order. - Having these things called out explicitly in isolation encourages people to get something working faster. In later sections, these examples are presented alongside many other options. Having to choose between alternatives gets in the way of quickly prototyping something. If you have further suggestions for how to improve or modify these docs I'm open to them. The changes included here would really make a huge improvement in the productivity of newer members of my team using this library.
nlohmann
requested changes
Jul 4, 2022
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.
A minor comment below.
jez
commented
Jul 17, 2022
jez
commented
Jul 17, 2022
jez
commented
Jul 17, 2022
nlohmann
approved these changes
Jul 18, 2022
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 to me.
Thanks! |
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.
We use this library extensively where I work. After pairing with many
teammates, I've learned that one common stumbling point when using this
library is how to first get a JSON value in the first place (because
once they have a variable of type
json
in hand, the API is intuitiveand mostly does what you expect).
With that in mind, I've added two subsections to the top of the Examples
section: how to read JSON from a file, and how to hardcode a JSON
literal.
I understand that these are already documented elsewhere in the Examples
section, and so these new subsections are technically redundant. But to
defend this choice:
Redundancy in docs is actually good, because not everyone consumes
docs in the same way or in the same order.
Having these things called out explicitly in isolation encourages
people to get something working faster. In later sections, these
examples are presented alongside many other options. Having to choose
between alternatives gets in the way of quickly prototyping something.
If you have further suggestions for how to improve or modify these docs
I'm open to them. The changes included here would really make a huge
improvement in the productivity of newer members of my team using this
library.
Pull request checklist
Read the Contribution Guidelines for detailed information.
include/nlohmann
directory, runmake amalgamate
to create the single-header filesingle_include/nlohmann/json.hpp
. The whole process is described here.Please don't
#ifdef
s or other means.