Clearer readme/docs

[StefanoMagrassi]

First of all: great job.

This project seems so useful and interesting and I would use it right now, but the readme/documentation it's a bit confusing to me: what is the meaning of BASTJ and ESBASTJ suffixes in the batteries package?

I think that the summoner and config parts should be a little clearer...

Maybe you can also use the gcanti/docs-ts package

[anthonyjoeseph]

@mikearnaldi, quoted from the slack channel (link to join here - channel #morphic):

BASTJ and ESBASTJ are the initials of the interpreters that are baked in:
E = Eq
S = Show
B = Build
etc

[sledorze]

summoner naming has been updated in the Readme
unsure if that's clear enough now, @anthonyjoeseph

[nibtime]

first of all, thank you for creating this library.

It would be nice if there was some sort of conceptual guide to explain the big picture behind the library. The README is more instructional/FAQ, which is of great importance also of course. What I mean is actually already there - the "How it works" section, but it is rather short.

Also, some sort of comparative overview that lists what io-ts can do and can't do, i.e. what morphic-ts does on top would be nice.

The biggest question for me is: If I have an existing domain model with lots of existing io-ts definitions - would I have to redeclare everything from scratch to get Morphs, or could I reuse them in some way?

At the moment I don't need really this library, what io-ts offers is enough for me. However, it would be nice to know if I can build on top of my io-ts work once I need some features of morphic-ts.

[akomm]

Also more info on peerDependencies. I get the following peer warnings, when installing @morphic-ts/batteries like said in the docs:

• root -> fast-equals
• root -> io-ts-types
• root -> newtype-ts
• @morphic-ts/batteries -> fast-check
• @morphic-ts/batteries -> fp-ts-contrib
• @morphic-ts/io-ts-interpreters -> fp-ts
• @morphic-ts/summoners -> io-ts
• @morphic-ts/summoners -> io-ts-types
• @morphic-ts/summoners -> newtype-ts

Whats unclear in docs: why do I need newtype-ts, io-ts-types? What is clear, probably need fast-equals, when using fast-check, right? Can I ignore it, when not using fast-check summoner?

Even when I add the peerDependencies expected in my root, I still get warnings from the other @morphic-ts libraries. The funny thing is, I actually have io-ts and fp-ts installed, but the packages above still complain. I guess its because they have libraries themself as dependencies, which have peer-dependencies, but don't add them.

You really should add more than just "install @morphic-ts/batteries" in the docs, when using what feature, what is needed or if something is always needed, then you should add it in the docs too

[akomm]

IMHO: The docs explain well, what the purpose of the library is. Have 1 definition and generate different things, like lenses (monocle-ts), codecs (io-ts) and more out of it.

But then the docs go about information as if you already know everything. I know for example the ADT library and I understand that I can access different things "summoned" via the batteries library, but whats the relation between the ADT library and the library with the summoners? You can use ADT independently, but they both give their own way of defining tagged unions for example.. The one ?probably? does it via io-ts and the other has own flawor. The docs just jump from the one to the other and tell "you can use it standalone" - yes I know, but what? Like where is the link? Are they independent? In the docs at the beginning its referred "see later ADT", but never explain what is meant. Or what about all the derive and configuration? What is the concept? Do I need to create a summoner for each type? I could probably answer the question myself, If I understood the configuration it needs, which you don't really explain. There are many missing links between concepts and concept explanation as a whole.

Don't get me wrong. I don't write it as some sort of expectation, its a free project, just in case you are not aware of it. If you just don't have the time for "full" docs, I guess then that's how it is. But sometimes if you know stuff, you've wrote, you don't realize "holes" in the explanation, because for you personally there is no hole ;P

[owonwo]

Hi @anthonyjoeseph

I saw your articles on Dev.to and they were very cool. However, I'm finding it difficult to locate the variables and types needed for the configuration of summoners. I would really love to get some insight those.