New documentation site

[millsp]

🍩 Feature Request

Is your feature request related to a problem?

The current docs website is OK but we could do better.

Describe the solution you'd like

We need to build a better documentation website with docz. This is a feature that does not exist within docz so we will have to:

• parse the code
• extract docs
• generate markdown pages
• link doc [[references]]
• link sources on repos

Describe alternatives you've considered

Teachability, Documentation, Adoption, Migration Strategy

[mesqueeb]

Just to give me 2 cents:
There are many types I'm not 100% sure of how & why to use. Some types are also similar to native TS types, so I often wonder the benefit of the TS-Toolbelt one over the native one.

If you want I can go through the entire list of types and write up one by one why I don't understand a type/example.
Let me know if this would help.

[millsp]

Yes, thanks, that would be amazing! This is great help :)

The idea behind ts-toolbelt having all of the types is that:

• Some of them fix non-obvious bugs (like the original Pick/Omit not working with unions)
• We provide a single API for the type system, replacing ts type utilities, that can evolve in the future as needed. Another example is Record, that used to be the same as ts' but now has options to make fields ? or readonly.

Looking forward to your comments on the docs! Thanks

[mesqueeb]

@millsp

I spent about 2 hours this morning reviewing the current types.

I have difficulties understanding why you provide wrappers like these:
How/why should we use them?

• Any/x
• Class/Class
• List/List
• Object/Object
• String/String
• Union/Union

& I have difficulties understanding almost everything under:

• Misc/…

Then I realised I only have real experience with your O / Object types, so I just focused my review on those types, and I went through the entire list and made notes:

Not 100% sure what it does exactly + it has no example:

• O.AtLeast
• O.Either
• O.Has / O.HasPath / O.Includes (I think this can be used for conditional TS types, but a specific example / use case would be really good here)
• O.ListOf
• O.Modify
• O.Union (what’s the use case?)
• O.Unionize

Not 100% sure what it does exactly even though it has an example:

• O.Invert (the example doesn’t really show what the resulting type is, making it difficult to reason about)

The difference is not super clear between:

• O.Diff ⇔ O.Intersect
• O.Keys ⇔ (native) keyof T
• O.Exclude ⇔ O.Filter ⇔ O.Omit ⇔ (native) Omit (also want to mention the native "Exclude" is easier to understand over O.Exclude because it’s not focussed on Objects)
• O.Pick ⇔ O.Select ⇔ (native) Pick
• O.Readonly ⇔ (native) Readonly
• O.Record ⇔ (native) Record
• O.Required ⇔ (native) Required (I do understand the advantage of O.Compulsory, but not of O.Required over the native option)

"Keys" variants:

• All of the "Keys" variants are quite difficult to understand imo (and maybe we should not show them in the docs, or make them searchable but don’t show them in the index on the left?)

"Up" variants:

• So I’m wondering if the "Up" variants can’t be the default behaviour and we get rid of the base types. It will reduce cognitive strain when people want to get familiar with your library.

"Path" variants:

• It’s not super clear if the type will return just what’s retrieved at the "path", OR it will make the changes at the "path" but return the entire object type again.

Overall:

• I think it’d be much clearer if each type has an example and the example actually shows how the new type will look when the ts-toolkit type is applied.

I hope this helps <3

[millsp]

Amazing, thank you so much for your feedback. Thanks for taking the time!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[waynevanson]

I like having documentation inline with the code. It's helpful and I don't really need to visit the docs too often unless I want to read everything and engage in some research.

in fp-ts, a package called doc-ts has been made to get the tsdoc comments and create a site with it: https://gcanti.github.io/fp-ts/.
Every new feature has the comments, so every release has up to date docs.

Would you interested in something similar? Surely we could generate an output for use with docz

[mesqueeb]

Fighting with the stale bot XD