[Rough Draft] Composition-API: Introduction

[shentao]

This PR is a draft of the Composition API: Introduction Tutorial.

Here's what the PR includes:

• Why would you want to use Composition API?
• Intro to setup option
• Intro to ref (`reactive is omitted in the introduction tutorial)
• Lifecycle hooks registration inside setup
• Intro to watch (watchEffect is omitted in the introduction tutorial)
• Intro to computed
• Extracting code into separate function/files

What's left to do:

• Build codepens (or codesandboxes for multi-file projects?) if we consider them necessary.
• The Notion draft included color highlighting for the code snippets which I think help with understanding what goes where during the refactor. See: https://www.notion.so/shentao/Composition-API-Introduction-e86b4fe667a5416bb8ee87542e168f0b
• Minor styling fixes to the output exported from Notion (images, headers)
• Decide if omitting reactive and watchEffect is a good idea. I believe it is and here’s my reasoning:
  • Regarding reactive – I don’t think we need to show two ways of doing the same thing at this stage, where I think the most important part is to show how the Option API can translate to Composition API. Also introducing reactive at this point could confuse the reader and is by no means justified by the code itself.
  • Similarly watchEffect doesn’t really have a counterpart in the options API (unless we consider how the render function is working 😅). Thus explaining it here would unnecessarily make the text longer and could sidetrack the reader by showing something that again is not necessary from the tutorial perspective.

Open to feedback! I think it might still be a bit too long...

Edit: Path to preview is /guide/composition-api-introduction.html.

[phanan]

Nice work! I've added a couple of wording suggestions, mainly to eliminate duplicates and filling words/phrases. You'll notice that in most cases I suggested a simpler and/or shorter expression (at least IMHO) :)

[shentao]

Thanks, @phanan for reading through it and providing suggestions! Loved all of them and already fixed the ones where it could be optimized.

[shentao]

It was supposed to provide some context to the image. Might skip that "colorful" part.

[shentao]

Yeah – leftover from Notion. Will have to convert in the editor! Good catch.

[NataliaTepluhina]

Great work @shentao! As I was doing a (p)review of the Notion doc, I don't have any additional comments 😅

[shentao]

Thanks @NataliaTepluhina! Let me know if there is any other way I could help out!

[znck]

Very long PR, I will continue reviewing it.

[znck]

This image appears out of context to me. I feel it would be better if we reuse the above snippet covey the intension. And a better resolution would be great.

[shentao]

Good call @znck! I just picked the image from the RFC page, since it explained the idea pretty nicely in a visual manner. I used the same thing a few times during talks and it was the part that proved to be very educative to the audience. What about using the second image where it shows the two files (pre and post composition API)?

[znck]

No doubt the image is good visual representation of logic fragmentation. I meant that we can use the above code snippet and highlight in a similar manner. Since readers have already read the code above, it would be easier for them to scan the coloured highlights.

[znck]

Yes, please.

suggestion: "logical concerns grouped by colours" should be the key focus of the paragraph and less dramatic text would be better to match overall writing style.

[znck]

suggestion: The heading feels more like from an article. Can we reword it (without Introduction maybe)?

[phanan]

One thing I forgot to mention: Let’s all use American English (IIRC this is mentioned somewhere in our writing guide) for our docs, so “color” instead of “colour” ;)

…

On Wed, 15 Apr 2020 at 07:57, Rahul Kadyan ***@***.***> wrote: ***@***.**** commented on this pull request. Very long PR, I will continue reviewing it. ------------------------------ In src/guide/composition-api-introduction.md <#67 (comment)>: > @@ -0,0 +1,540 @@ +# Composition API: Introduction + +## Why Composition API? + +::: tip Note +Reaching this far in the documentation, we are assuming that you are already familiar with both the basics of writing Vue code as well as the basics of creating components. If you’re not, you might want to first read through [Vue Introduction](introduction.md) and [Components Basics](component-basics.md) first before reading further. +::: + +Creating Vue components is a powerful technique that allows us to extract repeatable parts of the interface coupled with its functionality into reusable pieces of code. This alone can get our application pretty far in terms of maintainability and flexibility. However, our collective experience has proved that this alone might not be enough, especially when your application is getting really big – think several hundreds of components. When dealing with such large applications, sharing and reusing code becomes especially important. *nitpick:* I understand what you're trying to covey here but I feel the phrase "a powerful technique" is unnecessary as you're highlighting the powers of the technique in the following segment. ⬇️ Suggested change -Creating Vue components is a powerful technique that allows us to extract repeatable parts of the interface coupled with its functionality into reusable pieces of code. This alone can get our application pretty far in terms of maintainability and flexibility. However, our collective experience has proved that this alone might not be enough, especially when your application is getting really big – think several hundreds of components. When dealing with such large applications, sharing and reusing code becomes especially important. +Creating Vue components allows us to extract repeatable parts of the interface coupled with its functionality into reusable pieces of code. This alone can get our application pretty far in terms of maintainability and flexibility. However, our collective experience has proved that this alone might not be enough, especially when your application is getting really big – think several hundreds of components. When dealing with such large applications, sharing and reusing code becomes especially important. ------------------------------ In src/guide/composition-api-introduction.md <#67 (comment)>: > + }, + mounted () { + this.getUserRepositories() // 1 + } +} +``` + +This component has several responsibilities: + +1. Getting repositories from a presumedly external API for that user name and refreshing it whenever the user changes +2. Searching for repositories using a `searchQuery` string +3. Filtering repositories using a `filters` object + +Organizing logics with component's options (`data`, `computed`, `methods`, `watch`) works in most cases. However, when our components get bigger, the list of **logical concerns** also grows. This can lead to components that are hard to read and understand, especially for people who didn't write them in the first place. + + This image appears out of context to me. I feel it would be better if we reuse the above snippet covey the intension. And a better resolution would be great. ------------------------------ In src/guide/composition-api-introduction.md <#67 (comment)>: > + this.getUserRepositories() // 1 + } +} +``` + +As you can see, this component has several responsibilities: + +1. Getting repositories from a presumedly external API for that user name and refreshing it whenever the user changes +2. Filtering repositories based on a `searchQuery` text +3. Filtering repositories based on a `filters` object + +The above way of building components, enforces code that is organized by option types within the component itself (data, computed, methods, watch), which is OK in most cases. However, usually when our components grow the list of **logical concerns** is also growing. This can lead to components that are hard to read and understand, especially to someone that hasn’t originally written it. + + + +Please consider this colourful example on the side for second or two as it presents a larger component with its **logical concerns** grouped by colours. Yes, please. *suggestion:* "logical concerns grouped by colours" should be the key focus of the paragraph and less dramatic text would be better to match overall writing style. ------------------------------ In src/guide/composition-api-introduction.md <#67 (comment)>: > + +Organizing logics with component's options (`data`, `computed`, `methods`, `watch`) works in most cases. However, when our components get bigger, the list of **logical concerns** also grows. This can lead to components that are hard to read and understand, especially for people who didn't write them in the first place. + + + +Please consider this colourful example on the side for second or two as it presents a larger component with its **logical concerns** grouped by colours. + +Such fragmentation is what makes it difficult to understand and maintain a complex component. The separation of options obscures the underlying logical concerns. In addition, when working on a single logical concern, we have to constantly "jump" around option blocks for the relevant code. + +It would be much nicer if we could collocate code related to the same logical concern. And this is exactly what the Composition API enables us to do. + +## Basics of Composition API + +Now that we know the **why** we can get to the **how**. To start working with the Compsition API we first need a place where we can actually use it. In a Vue component, we call this place the `setup`. + +### Introducing `setup` *suggestion:* The heading feels more like from an article. Can we reword it (without Introduction maybe)? ------------------------------ In src/guide/composition-api-introduction.md <#67 (comment)>: > +setup (props) { + let repositories = [] + const getUserRepositories = async () => { + repositories = await fetchUserRepositories(props.user) + } + + return { + repositories, + getUserRepositories // functions returned behave the same as methods + } +} +``` + +This is our starting point, except it's not working yet because our `repositories` variable is not reactive. This means from a user's perspective, the repository list would remain empty. Let's fix that! + +### Introducing `ref` *suggestion:* Same as above, dramatic heading. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#67 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB5O3USJYJWUHTVTOOJRY3DRMVED3ANCNFSM4MH2B56A> .

[phanan]

Again, solid work @shentao! I'm using some free time before work to add a couple more super minor suggestions (some might even be the result of my last review!). My general idea is to keep the documentation as short and straightforward as it could be by:

• Merging/removing sentences/phrases that convey the same/similar message.
• Reducing the usage of filler and/or assuming phrases such as "As you know" or "You might have noticed." While these phrases add a friendly touch to the document, overusing them might lengthen (and dilute) the doc, cause a dramatic feel, and is prone to struggle invalidation.

[phanan]

The headings should have the same case (currently it's Title Case e.g., Ready for More?).

[znck]

@shentao You can use grammarly.com to catch issues like "color" instead of "colour" and there's a vscode extension too (shameless plug).

[shentao]

Thanks for the reviews @znck and @phanan (again!). Yeah, I do use Grammarly quite often. I think my system is just set to British English (gotta change that).

I’m not using VS Code!

[NataliaTepluhina]

As we have no further comments, I'm merging this PR 🎉