Add a "Usage" section to the README

[takanuva15]

Hi, could we add a "Usage" section to the README with just a short example of serializing and deserializing a basic python object? This will make it faster to get started with this library instead of having to jump over to the docs for python pickle to understand the correct way to call this library's methods

[davvid]

How do we know people will read this section if they didn't already read the intro section that links to the jsonpickle documentation?

That documentation already has a usage example and we shouldn't duplicate all of that stuff in the readme.

I'm not 100% sure that this will solve any perceived issues.

I would actually go in the other direction -- I would recommend slimming the README down and making it link to the documentation instead so that there's less duplication of effort and reading material.

This will make it faster to get started with this library instead of having to jump over to the docs for python pickle

We link to jsonpickle's documentation from the README. You don't need to read the python pickle documentation.

I'm not convinced that lazy readers is a problem that can be solved by... adding more reading material.

I'd be happy review a PR that updates the README with a Usage section that links to https://jsonpickle.github.io/#jsonpickle-usage though.

[Theelx]

Actually, I think Takanuva has a point, @davvid, but not for the reason they specified. When I google "jsonpickle" or " "jsonpickle docs", the first result I get is our outdated documentation from version 1.4.3. The GitHub page isn't even the in the first 3 results for either search (for me). Until that page is shut down, I think it may be useful to combine a short usage example on the GitHub with a slimmed-down README, so that anyone who happens to land on the GitHub after seeing the outdated docs notices that the library has changed significantly and how to get started.

[Theelx]

Also, I will say that when I'm under time pressure, I do often check the GitHub README instead of the documentation page, especially when I'm looking among alternatives for a library that fulfills a purpose. I can gather examples of the many python libraries that include a short Usage section, with ~2-5 lines of basic code in their GitHub READMEs, because there's a good reason it's not uncommon for libraries to include such a section.

lazy readers

As much as I would hope that users would read all the documentation, I don't think that thinking about people who don't read everything as lazy is a practical mindset. There are many people out there who may be under time pressure because of a demanding job, demanding school studies, or other reasons, and judging them for needing a quick solution instead of spending hours reading the documentation for every library can sometimes be counterproductive. I think that saving users time is something that motivates a large portion of best practices in the UI/UX field, and I don't think any project, let alone one with 300k+ daily downloads on PyPi, is an exception.

[davvid]

True that, sorry for the (knee-)jerk initial reaction. That reminded me that I should update jsonpickle.github.io so I did that just now.

I'll add a garden file for handling that shortly so I don't have to remember the manual steps I ran.