Skip to content
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
merged 4 commits into from
Jul 18, 2022

Conversation

jez
Copy link
Contributor

@jez jez commented Jun 27, 2022

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.


Pull request checklist

Read the Contribution Guidelines for detailed information.

  • Changes are described in the pull request, or an existing issue is referenced.
  • The test suite compiles and runs without error.
  • Code coverage is 100%. Test cases can be added by editing the test suite.
  • The source code is amalgamated; that is, after making changes to the sources in the include/nlohmann directory, run make amalgamate to create the single-header file single_include/nlohmann/json.hpp. The whole process is described here.

Please don't

  • The C++11 support varies between different compilers and versions. Please note the list of supported compilers. Some compilers like GCC 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support. Please refrain from proposing changes that work around these compiler's limitations with #ifdefs or other means.
  • Specifically, I am aware of compilation problems with Microsoft Visual Studio (there even is an issue label for these kind of bugs). I understand that even in 2016, complete C++11 support isn't there yet. But please also understand that I do not want to drop features or uglify the code just to make Microsoft's sub-standard compiler happy. The past has shown that there are ways to express the functionality such that the code compiles with the most recent MSVC - unfortunately, this is not the main objective of the project.
  • Please refrain from proposing changes that would break JSON conformance. If you propose a conformant extension of JSON to be supported by the library, please motivate this extension.
  • Please do not open pull requests that address multiple issues.

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.
@jez jez requested a review from nlohmann as a code owner June 27, 2022 17:09
@coveralls
Copy link

coveralls commented Jun 27, 2022

Coverage Status

Coverage remained the same at 100.0% when pulling fbc9289 on jez:jez-readme into 954b10a on nlohmann:develop.

@nlohmann nlohmann self-assigned this Jul 4, 2022
Copy link
Owner

@nlohmann nlohmann left a 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.

README.md Show resolved Hide resolved
@jez jez requested a review from nlohmann July 6, 2022 17:02
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
Copy link
Owner

@nlohmann nlohmann left a 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.

@nlohmann nlohmann added this to the Release 3.11.0 milestone Jul 18, 2022
@nlohmann nlohmann merged commit 2a9ae2b into nlohmann:develop Jul 18, 2022
@nlohmann
Copy link
Owner

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants