io-ts
io-ts copied to clipboard
gcanti
Readme is empty, should contain a simple and elaborate example plus the list of available types
📖 Documentation
As a long time user I tried recommending io-ts to someone, but they were weren't convinced because they couldn't figure out how to use it. The documentation, while fairly complete, is not structured very well.
Currently, the readme is empty, and of the 6 links it contains, 5 of them are useless for first-time users, while the only useful one (link to Type.md) is unclearly labeled and contains more information that is only useful for very advanced use cases.
In my opinion, the first thing the readme should contain is a simple example showing the most commonly used combinators, the TypeOf<> type, and a simple validate call. Below, it should have the list of combinators currently hidden in https://github.com/gcanti/io-ts/blob/master/Type.md#implemented-types--combinators (this was previously the case)
Those two things would be enough to satisfy 95% of documentation needs - I doubt most people care about the internal workings of io-ts, or at least it's not what they want to see first.
i believe there was a readme! right now it is empty. Please, do not do the same mistake i had: do not move OSS documentation out of github markdown, this is so far the only good way. I had some OSS projects in the past that tried to do so - it was awful.
@phiresky Before you add a link to a file in a repository, you should expand a URL to its canonical form by pressing y. The two links in your post are now 404s. See Getting permanent links to files
@gcanti would you be open to a PR reordering the documentation a bit to make this library more clear to understand for beginners? As is, it's really hard to recommend this great library to people because it's "impossible" to understand for people that don't care about functional programming theory. index.md basically starts with multiple things I'd dare say are useless and confusing for almost all new users of this library. Almost no one has to know the exact definition of the Type<A, O, I> interface or the Either<> interface or how to define t.string() myself.
would you be open to a PR reordering the documentation a bit to make this library more clear to understand for beginners?
Certainly, thank you. What do you think of the @fp-ts/schema documentation? If it's okay, we could take its documentation as a reference.
Oh yeah, that looks a lot better. Wait, is @fp-ts/schema like a successor to io-ts?
is @fp-ts/schema like a successor to io-ts?
Kind of, you can consider it as the next major iteration of io-ts but the goal is a bit wider and involves compiling a schema to other artifacts in addition to decoder and encoder, so there is a lot of overlap but also some differences and the engine underneath has been completely rewritten from scratch.