Improve documentation, error messages

It is a great package providing all data modeling capabilities and serialization that I want, thank you.

But the problem for me was that I had to gather info about how to use it in different places: examples, code documentation, different articles, API reference, stack overflow, and it took some time. Also current documentation contains outdated info like using `@nullable` to mark fields as `nullable` instead of `?` syntax.

I see that people are struggling to get documentation as well: #830, #1040, #579, #736, #670, etc.

I think that it would be great to improve documentation:
* update it;
* collect everything (different articles, examples info) in one place to README;
* separate theory info (like [value types](https://pub.dev/packages/built_value#value-types), [enum class](https://pub.dev/packages/built_value#enum-class) of current README) from practical usage info with examples (like [common usage](https://pub.dev/packages/built_value#common-usage) section of README). add small examples showcasing each of mentioned sections;
* add info about using custom serializers, json serializer, serializer plugin, etc.

I think it would make this package much more simplier to use for newcommers. And I would be happy to help doing so if you argee on that and maybe provide your vision of this problem.