Mention what JSON:API solves in the README

[verdie-g]

Is your feature request related to a problem? Please describe.

Currently, the README correctly explains what this library solves but it assumes that the reader already knows what JSON:API is about. There is a link to the blog post "What is JSON:API and why should I use it?" later but at this point you probably already lost the attention of the reader.

I think many developers could learn about JSON:API through this library rather than looking for this library after learning about JSON:API.

Describe the solution you'd like

The README could mention at the top:

1. What problem does JSON:API solve
2. Add a request/response example
3. Then, explain how this library helps implementing a JSON:API

What do you think?

[bkoelman]

Thanks for bringing it up. There's room for improvement.

Currently, the README correctly explains what this library solves but it assumes that the reader already knows what JSON:API is about.

Yes, and it's common for READMEs to assume familiarity with the technology upfront. Some examples:

• The EF Core repo doesn't explain what SQL is.
• The xUnit repo doesn't explain why one should write tests, or what unit/integration tests are.
• The roslyn repo doesn't explain why one should code in C# or VB, or even what a compiler is.
• The FluentAssertions repo doesn't explain its purpose.

All that information is available on documentation sites, blog posts, videos, etc. In my experience, it's best practice to get to concrete details quickly. Developers generally don't like to scroll through lots of text first, they prefer to see a code sample quickly.

That's also in line with the NuGet README recommendations:

• Start with a clear and concise description: Start your README with a brief overview of what your package is and does, also what problem it solves.
  • We do: eliminate boilerplate, focus on business logic, extendable. Tech-stack: ASP.NET, EF Core, JSON:API with operations.
• Explain how to use it: Provide clear and concise getting started instructions for using your package, including any necessary steps.
• Provide links to more resources: List links such as detailed documentation, tutorial videos, blog posts, or any other relevant documentation to help users get the most out of your package.

We have steps 2 and 3 reversed. We could move the existing sample code above Getting Started, but it should remain a JADNC example, not a JSON:API example. Because that's what the project is about. Roslyn doesn't show the MSIL it produces either, because it's providing an abstraction on top of that to ease usage. Likewise, we provide C# support to make working with JSON:API easy (server-side, at least). But we could define the same resources as in the GettingStarted project here, then link to https://www.jsonapi.net/request-examples/index.html for what that enables.

It would be good if the Getting Started section explicitly linked to the getting-started steps in the docs.

Related projects could be moved way down, as well as the compatibility table.

I think many developers could learn about JSON:API through this library rather than looking for this library after learning about JSON:API.

That's just an assumption. By far the most web traffic we get is from users googling for JSON:API and its related terms. Here's the current top 10:

• jsonapidotnetcore
• json api c#
• json api filter
• c# json api
• jsonapi
• json api pagination
• jsonapi relationships
• json api meta
• json api query parameters
• json api include

I don't mind if developers follow our external links to familiarize themselves with JSON:API, but it's not our primary audience. For example, I've encountered Java developers looking for a .NET equivalent for JSON:API. Elaborating on what JSON:API is comes at the cost of losing existing readers. And I don't want to duplicate and maintain all the existing great documentation on JSON:API that's already out there. If you happen to know nice links, feel free to propose adding them to the list.

I'm open to ideas, but it helps to provide specific detailed suggestions. Then we can reason about whether the proposed text/sample makes sense.

[verdie-g]

it's common for READMEs to assume familiarity with the technology upfront

I'm not sure we can compare SQL, C# or tests to JSON:API because the former are ubiquitous technologies while I'm pretty confident not a single of my co-workers know about JSON:API.

That's just an assumption. By far the most web traffic we get is from users googling for JSON:API and its related terms.

Personally, I usually discover Github projects through what the people I follow on Github starred, or contributed to.

We have steps 2 and 3 reversed

Agreed.

Going through the README again, I think I would be fine with just some reordering + curl examples.

What do you think about that layout

# JsonApiDotNetCore // Unchanged

## Installation and Usage

## Examples // Maybe "More Examples"?
Here I would probably also add a curl GET example to give an idea about the JSON:API
document. If it's not too much, a POST example would be nice to show that the same
document is used everywhere.

## Getting Started
Here it's currently links to blog posts. I'm expecting what's currently in "Installation and
Usage" in a section named "Getting Started". Maybe it can simply be renamed to "Resources".

## Related Projects

// the rest doesn't change

[bkoelman]

I'm not sure we can compare SQL, C# or tests to JSON:API because the former are ubiquitous technologies while I'm pretty confident not a single of my co-workers know about JSON:API.

These technologies are ubiquitous for you personally, because you're a .NET developer. It'd be surprising if your co-workers knew JSON:API. Because developer advocates are not actively promoting it at .NET conferences. No technical writers are pushing for their posts to be included in .NET newsletters. No strategic partnerships with .NET consultancy firms exist that introduce it at customer sites, etc.

Analytics indicate that this repository is primarily attracting developers (of all sorts) who are interested in JSON:API. In Ember.js, JSON:API is a ubiquitous technology. Such a visitor may only be superficially familiar with .NET, which we don't introduce either.

I don't have evidence that JADNC primarily attracts .NET developers. Do you? A substantial amount of questions originate from developers who hardly know how to use .NET, so I doubt that's the case. Some time ago, JSON:API experts asked me to help them better understand ASP.NET and EF Core during their commercial JADNC project.

Personally, I usually discover Github projects through what the people I follow on Github starred, or contributed to.

Yes, people find what's "in their bubble". Imagine there are bubbles centered around JSON:API finding this repository.

Going through the README again, I think I would be fine with just some reordering + curl examples.

I'm concerned full curl examples take up too much space.

## Installation and Usage ## Getting Started

Isn't "Installation and Usage" and "Getting Started" the same thing? I consider installation part of getting started.

Maybe it can simply be renamed to "Resources".

That's an overloaded term we should avoid here.

[bkoelman]

As part of these changes, we should reverse the order of the version table, so that latest versions appear at the top.