docs: refactor (WIP)

[tobySolutions]

Please describe the changes this PR makes and why it should be merged:

This here will contain changes to the docs based on feedback gotten from Sarah Kim (From Solidjs)

Status

• Code changes have been tested against prettier, or there are no code changes
• I know how to update typings and have done so, or typings don't need updating

Semantic versioning classification:

• This PR changes the codebase
  • This PR includes breaking changes (methods removed or renamed, parameters moved or removed)
  • This PR changes the internal workings with no modifications to the external API (bug fixes, performance improvements)
• This PR only includes non-code changes, like changes to documentation, README, etc.

[github-actions]

Thanks for opening this pull request! A maintainer will review it soon.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
million-kitchen-sink	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 23, 2023 0:37am
sink	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 23, 2023 0:37am

[coveralls]

Pull Request Test Coverage Report for Build 7308254324

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 25.706%

---

Totals
Change from base Build 7146800665:	0.0%
Covered Lines:	1257
Relevant Lines:	5082

---

💛 - Coveralls

[tobySolutions]

Check this out, please @aidenybai, @SukkaW.

[LadyBluenotes]

I did a more fine-toothed run through of some other pages and here's some comments from there:

"Virtualization"

• I would replace plays very well - what do you mean to say by this?
• I see div just under the heading "Example" that should be wrapped in backticks

Internals -> block()

• when referring to props, make sure that you whenever you're referring to it you are wrapping it in backticks.
• Some sentences read choppy. I would try and find a way to avoid redundancy and make it a bit more straightforward. As an example:

The props are filled with `Hole` values. These `Hole` values are replaced with the actual values when the `block()` is called. The `Hole` values are immutable and cannot be derived with other values.

Internals - "Patch"

• Can shorten the following to something like what I wrote:

Always try to keep Blocks of the same shape (derived from the same function) when using patch in order to maintain good performance.

// to

Blocks must be derived from the same function when using `patch()`. This ensures performance is not negatively impacted.

Some comments I may've missed last time:

• When you are talking about something that may have it's own page, you should interlink it. This helps with SEO and it can provide users with a direct link to where they need to go should they have any further questions.
• With the few Internals you have, the warning should be a bit more specific (I listed the one I'm referring to before. The reason I say this is that users may come across this and be confused by what you mean. Are there any situations someone may be using the specific Internal API function's in an app? If not, the "should" can be removed in lieu of something a bit more specific:

This function is part of the internal API. You should only be using this if you are making your own framework.

// if you need to tell them explicitly "DONT USE"

This function is part of the internal API. It is intended for developers creating their own frameworks. It is not recommended for general use.

Again, let me know if you have any questions :)

[LadyBluenotes]

Suggested change

	Blocks can be used just like a normal React component:
	A block can be used within your application like a normal React component:

[LadyBluenotes]

In thinking about this page I'm not sure how introducing a basic example here helps. Maybe once you start getting into describing what is happening after creating a block, bringing in this info can be helpful.

For example, with this being a tutorial you want to introduce concepts as you go. Remember that Diataxis offers the suggestion that a Tutorial's purpose is to give the user basic competency. This includes throwing in a bit of info here and there that can help comprehension.

If you want this to be a guide, however, you're taking the user through a series of instructions on how to achieve a final outcome (eg. how to create a block out of an existing application). You don't really need to add any further information than is necessary.

[LadyBluenotes]

I might suggest rethinking what you want out of this page (tutorial vs guide) and restructuring it based on that 🙂

[tobySolutions]

@LadyBluenotes this is the one that prompted me to ask if we could have a meeting or just an async conversation around everything that needs major restructuring

[LadyBluenotes]

Got it!

I'll make a separate comment regarding all the questions.

[LadyBluenotes]

Not sure this needs to be an aside / what the purpose of this is.

If you want to show what an error message looks like, might be better to show what the console errors may look like.

[LadyBluenotes]

Some comments regarding this page:

• The Error messages are probably better suited for code blocks vs asides. This makes them look (imo) out of place, whereas a snippet of what the error message looks like in the console could be better.
  A pattern you can follow:

When you have a block that is not declared as a variable, you may encounter an error message (or warning?):

`[Million.js] Block needs to be defined as a variable declaration.`

This message tells you that the compiler can not analyze the block correctly and ... [explain examples of why]

[insert examples of errors & corrections here]

• I tend to follow this example vs telling someone to "look above" because I want a page to have flow. Meaning you read it top to bottom. Now this is more personal preference, but I find having moving up and down the page to get context can be disorientating
• There's still some emojis on this page outside of code blocks I would remove. Using ❌ and ✅ are nice to emphasize points in code where italics and bolds can't be used

[tobySolutions]

Hmm, thank you very much for these @LadyBluenotes, I'm gonna be adding these feedbacks soon to make the necessary updates.

[tobySolutions]

A lot of these are mostly nitpicks, so feel free to use them or not. If you have any questions regarding what I suggested, let me know.

Some comments just for overall docs writing:

• Try to avoid using contractions (don't, let's). This is mostly just for ease of reading / helping people who are ESL.
• Avoid using common "turns of phrase". These can shorten things dramatically and, again, helps with people who are not natively English speaking.
• When you are referring to the user, you don't want to assume any of their knowledge. Saying things like "you may have heard" is more something for blog posts vs docs. If you want to "talk" to them specifically, it should be in reference to steps vs what they should / should not know.
• For ease of editing, having each sentence on it's own line can make your life easier. That way if you have to edit one thing in one sentence, you don't have to look at a really large suggestion.
• Write with certainty unless there are cases that it is not necessary. Saying words like "technically" introduces confusing. If you have you encounter a situation where it is necessary to say something may or may not happen, you can use "while x can occur, y is the expected" or something like that.
• Are internals and the reference section different? They may need to be better classified.
• I think your structure has improved! It's a lot easier to follow (imo)

With the Rules of Blocks page:

• I'd avoid the "you are probably here". Just start with something like "When working with blocks, there are 3 common reasons you may encounter errors:".
• You can avoid adding "you" in each bullet point:

1. Breaking [rules of blocks](#link-to-section)
2. Not [adding the compiler](#link-to-section)
3. Encountering [unsupported behaviour](#link-to-section)

This is all I have to say at the moment! This is a bit beefy of a review, but let me know if there's any questions or comments. That includes if you don't agree with me 😁

Thank you very much for the Google resource!

[tobySolutions]

It is intended for developers creating their own frameworks. It is not recommended for general use.

Much appreciated. Thanks for this.

[tobySolutions]

@tobySolutions Which cases are you referring to me having seen?

Like are there cases in the docs where you've seen that general advice you mentioned weren't applied by me maybe?
I'm just asking generally, really.

I'm going to assume you're referring to avoiding the use of contractions, expressions, etc?

If you're wondering about those specifically, Google has a good technical writing course that helps with foundations (https://developers.google.com/tech-writing/overview). A lot of the information I've gained is reflected in that course. There are a few talks I can forward you, too, that go into what "good" documentation looks like.

Additionally, I learned from a few mentors what they've seen as most effective when they write. With editing, having sentences on their own lines (in markdown, specifically), makes the review process easier, for example. You can better target sentences and it improve readability during the editing process (eg. easier to identify grammar mistakes, sentences that could be shortened, etc. because you don't have to sift through a large paragraph).

If I'm misinterpreting the question, please let me know.

You answered perfectly. Could you maybe forward those talks and maybe expatiate on the one-line thing? Thanks

[LadyBluenotes]

So re: structure of the pages.

Tutorial & Guides

Tutorials and guides are hard to distinguish (IMO) but they serve two very different things. They both, as an example of how they're similar, provide directions for the user to follow. They're used as a means to tell the user what to do more than what they need to know.

They do, however, serve different needs.

Tutorial

• Someone who is studying and wants to learn the general skills / principles of something
• More learning orientated - basically learning skills through the hands on experience
• Gets the user familiar with the product (in this case million)
• An example of this: Creating a block component
• This kind of thing is aimed at just teaching. Meaning you don't introduce any confusion to the person following.
• Does not assume any knowledge other than the basics
• More specific

Guides

• Help the user who already has a basic idea of what is going on complete a particular task.
• Directs the users work but can lead to different routes - meaning you can say "you could do x but you can also do y"
• Relies on the user's already present knowledge
• More general

What I meant by the Usage Guide was more that it follows more of a tutorial-based format than the guide based one (which I don't think is a bad thing, just unsure of what you want of it).

For example, you could split the page up because right now there is a lot happening within the one page and it's hard to follow. What I might do if I were you was:

• Tutorial on how to integrate million into an existing application. This can include any information necessary for someone who is looking to integrate into their existing app and wants to know what it would look like explicitly.
• Guide on optimizing list rendering. You have this already, just making it into its own page would be a better idea imo. Good opportunity to show how to use <For>.
• Guide on blocks. This can start superficial then dive deep into the topic that you mention at the end - Hitting the limit

I think this better represents Million and provides users an easier place to navigate.

References:

Now with regards to the API Reference section and Internals - I think that there is some duplicate knowledge here going on. For example, block() is mentioned twice.

With regards to internals: These are supposed to act as the source of truth for Million. For people who just want to get into the details of certain things, they can go here. This can include typing (if relevant), use cases, and possibly any edge cases that they may run into. These aren't intended to teach just to give facts. This page is a good example of a reference - https://docs.astro.build/en/reference/integrations-reference/ .

I think that you should introduce a general Reference section that includes everything from internals plus <For>. You have the warnings for the functions that are not intended to be used for general use, so you don't really need to separate the both of them.

Regarding structure of them, they should all follow the same "recipe", if you will. I do think you do a pretty good job of this but you want to make sure that you add a bit more information, if possible. I know Solid has some pretty short pages, but having a good reference section can eliminate a lot of questions people ask. This can, hopefully, be shown when people are asking more specific / niche questions vs having to point them to different areas.

I believe right now your API Reference section follows more of a Guide format and that you could probably add <For> into the reference section, too, for people to quickly look them up.

Wrap up

Now all of this is to say, I don't think what you have is bad by any stretch of the imagination, this is simply an observation from what I have seen. If I were to propose a layout change, I might suggest the following (this is just an idea you don't need to follow the names at all lol)

_Getting Started_
Intro
Installation

_Basics_
How Million works
Block rules
Automatic Mode
Using with TypeScript

_Tutorial_
Integrate million into your existing project

_Guides_
Creating a block
Optimizing list rendering
Virtualized lists

_Reference_
`block`
`<For>`
`mount`
`patch`
`mapArray`
`renderToTemplate`

Again this is a very rough structure, so let me know if you have any specific questions on why. It might be a bit more work upfront, but I find it can help in the long run by making it easier to update the docs and, if you need to, remove things if you end up deprecating something.

[tobySolutions]

Now all of this is to say, I don't think what you have is bad by any stretch of the imagination, this is simply an observation from what I have seen. If I were to propose a layout change, I might suggest the following (this is just an idea you don't need to follow the names at all lol)

Hmm, thank you very much for this, Sarah. I really appreciate this. I'm gonna be making the updates this night after all my activities. Thank you very much for real @LadyBluenotes; you're super awesome!

[tobySolutions]

I'll be tackling this in tomorrow's stream!! Live

[tobySolutions]

Finally, the docs is done thanks to this live stream with I and @Drex72:

https://www.youtube.com/watch?v=4YCwRDB8q70

So, we've been able to make updates to the docs and shipped a new and improved documentation for users of Million's tooling.

Thank you @LadyBluenotes for being the best, @Drex72, @ricardonunez-io, @aidenybai!

I'll merge this now