DRAFT: Improve onboarding with documentation guides

[JesusTheHun]

After discovering Arktype a few weeks ago, I struggled to migrate from zod to arktype.
I felt the documentation lacked some walkthrough to discover the concepts from the arktype perspective.

To me, there are two main reasons for that :

1. Some features are simply not documented
2. The menu items are named after the concept name and not the usage

Many built-in types have just no documentation as well as many utility functions like type.Record which don't have JSDoc either.

Take the menu items Keyword > this for example.
When I'm searching into the documentation, I will not look for this, simply because I can't tell that's the solution to my problem.
If the item was named Recursive type, and then I was introduced to the this keyword, the discovery would have been more natural.

So I drafted this PR, introducing guides.

The Guides section aims to walkthrough user cases, rather providing an exhaustive API reference.

In its current state, I feel like all the documentation is really an API reference, with the exception of a few pages.

Going further, we could merge the other menu items into three big pages :

1. Syntaxes where one can read all the available syntaxes and ways to build a type.
2. Built-in types that contains all the built-in types and transformations available.
3. API Reference that describe all functions available within type.

So, what to do with this PR ?

If you think I'm going the right direction, let me know in the comment and I will work on the next steps as I described them.

As for now, the guides pages overlap with existing pages, so I don't think it's ok to merge this PR as it is.
Given you validate the goal, we could merge this PR once I've written a guide page on transformations.
A future PR can proceed with the merging of the menu items and the redaction of the exhaustive reference pages.

[ssalbdivad]

Wow, thanks so much for all the work on this! Definitely really enjoy the conversational tone introducing the various examples😊

I should have mentioned I'm also working on restructuring the documentation on the rc24 branch.

I'm hoping this will address a lot of the issues with the existing sections being unintuitive as an external user, but would definitely love more feedback on that.

Here are the sections I'm working on now:

As I'm fleshing out these categories, I'm definitely going to try and leverage a lot of these great examples. Hopefully it will be easier to contribute to the docs in a granular way now that there is more of a clear structure to what I'm looking to include and how I want to group it.

Let me know if you're interested in contributing more as I could definitely use the help and have some ideas for parts of the docs where I think you could help a lot without conflicting with what I'm working on.

[JesusTheHun]

I should have mentioned I'm also working on restructuring the documentation on the rc24 branch.

I browsed a bit, and from what I can see you've made significant work on the API Reference side, our works do not conflict nor overlap I believe.

As I'm fleshing out these categories, I'm definitely going to try and leverage a lot of these great examples

Do you agree with merging all the current items (and those on rc24) into the big categories I've laid out ?

Because the description of each type or function if often very short, and in order to disrupt the user's focus with navigation, I strongly believe we should have one big pages.
The menu on the right will help the discovery and navigation if needed.

Having numerous items in the left menu is, I believe, more confusing than helpful.

Let me know if you're interested in contributing more as I could definitely use the help and have some ideas for parts of the docs where I think you could help a lot without conflicting with what I'm working on.

I'll be happy to make more contributions. If you need my feedback, open a PR so I can share some thoughts in the review ;)

Should I keep working on this PR ?

The next steps would be adding a Transformations guide and removing the Intro section (now superseded by the guides).
EDIT : I forgot, I want to add an Error management guide before merging this PR.

We can discuss improvements beyond the scope of this PR in the Discussions or on Discord.

[ssalbdivad]

I've thought a lot about the lay out and am happy with it the way it is for now.

It's definitely good to have the context that this kind of break down makes more sense for you. Perhaps you could publish some kind of alternate "Intro to ArkType Coming From Zod" you could use for some marketing as well?

To me, the new structure seems like a good way for people to easily find the category they need at a glance while still breaking the project down clearly into its most important parts.

With regard to the intro in particular, that is the section of the docs I initially invested the most time in and thought was a good overview of the most important parts of the project. If you feel like there are issues with it, I'd be interested to know more about exactly what those are. People will have different intuitions about the easiest ways to understand something but it seems like a good overview of the most important topics to me.

[JesusTheHun]

Intro to ArkType Coming From Zod

Do you mean outside of ark documentation ?
Or renaming the Guides section into something like ArkType Coming From Zod / Migrating from Zod / Migrating to Arktype ?

To me, the new structure seems like a good way for people to easily find the category they need at a glance while still breaking the project down clearly into its most important parts.

I also think the new structure of the content is great, just not menu-wise. It's too big imho.

With regard to the intro in particular, that is the section of the docs I initially invested the most time in and thought was a good overview of the most important parts of the project. If you feel like there are issues with it, I'd be interested to know more about exactly what those are. People will have different intuitions about the easiest ways to understand something but it seems like a good overview of the most important topics to me.

In my opinion, it is a good overview. Now, one has to consider less experienced developers to whom this can feel too densely mixed-up or intricated. Many concepts or topics are brought up at the same time, I feel like it makes it difficult to explain the concepts in a calm and simple way. 🎵 When thinking about the rhythm, I'm thinking piano instead of drums.

What should I do with this PR then ? I'm confused now 😅

[ssalbdivad]

Interesting. Well I'll keep an eye out for feedback about the intro being overwhelming in the future, but you might notice in other cases I've marked sections like scopes and generics as advanced to indicate that users don't need to feel obligated to understand those to use the library, whereas they were among the first few topics you covered in your overview, so I'm not sure that overall I'm necessarily forcing people into more depth. Maybe it's just not explained in a way that feels helpful to you?

I will adapt some of the examples from your work to the docs I'm working on, but I don't think it makes sense to move forward with a PR with this content, especially as an alternative to the content I've already completed.

I do think there are good opportunities to contribute to the docs, especially by adding JSDoc for each keyword and working on a script that can convert those to .mdx. Otherwise with regard to the layout, I think it makes more sense for me to be the person to be working on that.