docs: update copy in getting started (#3741)

kapunahelewong · web-flow · commit 3eb26ab9aeb0 · 2023-04-12T15:51:39.000-05:00
diff --git a/packages/docs/src/routes/docs/(qwik)/getting-started/index.mdx b/packages/docs/src/routes/docs/(qwik)/getting-started/index.mdx
@@ -22,36 +22,36 @@ import CodeSandbox from '../../../../components/code-sandbox/index.tsx';
 
 # Getting Started Qwikly
 
-Qwik is a new kind of framework that is [resumable](../concepts/resumable/index.mdx) (no eager JS execution and no hydration), built for the edge and [familiar to the React developers](/docs/guides/qwik-react/).
+Qwik is a new kind of framework that is [resumable](../concepts/resumable/index.mdx) (no eager JS execution and no hydration), built for the edge and [familiar to React developers](/docs/guides/qwik-react/).
 
-If you want to play with it right away, try our in-browser playgrounds:
+To play with it right away, check out our in-browser playgrounds:
 
 - [StackBlitz Qwik](https://qwik.new) (Full Qwik + Qwikcity integration)
 - [Examples playground](/examples/reactivity/counter/) (Qwik only (no routing))
 
 ## Prerequisites
 
-If you want to get started with Qwik locally, you will need the following:
+To get started with Qwik locally, you need the following:
 
 - [Node.js v16.8](https://nodejs.org/en/download/) or higher
 - Your favorite IDE ([vscode](https://code.visualstudio.com/) recommended)
-- Optionally you may want to read [think qwik](../think-qwik/index.mdx)
+- Optionally, read [think qwik](../think-qwik/index.mdx)
 
 ## Create an app using the CLI
 
-The first step is to create a Qwik application with our CLI. The CLI will create a blank starter so that you can quickly familiarize yourself with it. Qwik supports NPM, yarn and pnpm.
+First, create a Qwik application with the Qwik CLI, which generates a blank starter so that you can quickly familiarize yourself with it. 
 
-Run the Qwik CLI in your shell. Choose the package manager you prefer and run one of the following commands:
+Run the Qwik CLI in your shell. Qwik supports NPM, yarn and pnpm. Choose the package manager you prefer and run one of the following commands:
 
 ```shell
 npm create qwik@latest
 pnpm create qwik@latest
 yarn create qwik@latest
 ```
 
-The CLI will guide you through an interactive menu to set the project-name, select one of the starters and asks if you want to install the dependencies. To find out more about the files generated by reading up on the [project structure](/docs/project-structure/).
+The CLI guides you through an interactive menu to set the project-name, select one of the starters and asks if you want to install the dependencies. Find out more about the files generated by referring to the [Project Structure](/docs/project-structure/) documentation.
 
-Start the development server
+Start the development server:
 
 ```shell
 npm start
@@ -61,16 +61,14 @@ yarn start
 
 ## Qwik Hello World
 
-To get you familiar with Qwik we have created a very simple "Hello World" application tutorial that touches on the most important concepts of Qwik. For each part we touch on we will link you to the relevant documentation where you can find out more about the given concept.
-
-We will use https://icanhazdadjoke.com as our API to get a random joke. We will create a simple application that will display a random joke and a button to get a new joke.
+The Qwik Hello World tutorial guides you through building a joke app with Qwik while covering the most important Qwik concepts. The app displays a random joke from https://icanhazdadjoke.com and features a button to get a new joke on click.
 
 
 ## 1. Create A Route
 
-Everything starts by serving a page at a particular route. So let's build a simple app that serves a random dad joke application on `/joke/` route. Qwikcity (Qwik's meta-framework) uses [directory-based](/docs/routing/) routing. To get started:
+Start by serving a page at a particular route. This basic app serves a random dad joke application on the `/joke/` route. This tutorial relies on Qwikcity, Qwik's meta-framework, which uses [directory-based](/docs/routing/) routing. To get started:
 
-1. Create a new `index.tsx` file in the `src/routes/joke/` directory in your project. (You will need to create the `joke` directory first.)
+1. In your project, create a new `joke` directory in `routes` containing an `index.tsx` file.
 2. Each route's `index.tsx` file must have an `export default component$(...)` so that Qwikcity knows what content to serve. Paste the following content to `src/routes/joke/index.tsx`:
 
 <CodeSandbox src="/src/routes/demo/getting-started/01-route/index.tsx" style={{ height: '6em' }}>
@@ -88,11 +86,11 @@ export default component$(() => {
 > NOTE:
 >
 > - Your `joke` route default component is surrounded by an existing layout. See [Layout](/docs/layout/) for more details on what layouts are and how to work with them.
-> - For more details about how to author components see the [Component API](/docs/(qwik)/components/overview/index.mdx) section.
+> - For more details about how to author components, see the [Component API](/docs/(qwik)/components/overview/index.mdx) section.
 
 ## 2. Loading Data
 
-A common thing a page does is load data to display to the user. This is performed using [route loaders](/docs/route-loader/).
+To load data to display to the user, use [route loaders](/docs/route-loader/).
 
 1. Open `src/routes/joke/index.tsx` and add this code:
 
@@ -120,18 +118,20 @@ export default component$(() => {
 });
 ```
 
-3. Navigate to `http://127.0.0.1:5173/` to see the application running.
+3. Now on `http://localhost:5173/joke/`, the browser displays a random joke.
 
-What does the above code do?
+Code explanation:
 
 - The function passed to `routeLoader$` is invoked on the server eagerly before any component is rendered and is responsible for loading data.
-- The `routeLoader$` returns a use-hook (`useDadJoke`) that can be used in the component to retrieve the server data.
+- The `routeLoader$` returns a use-hook, `useDadJoke()`, that can be used in the component to retrieve the server data.
 
 > **NOTE**
 >
 > - The `routeLoader$` is invoked eagerly on the server before any component is rendered, even if its use-hook is not invoked in any component.
 > - The `routeLoader$` return type is inferred in the component without the need for any additional type information.
 
+For reference, the complete code snippet for this section is as follows:
+
 <CodeSandbox src="/src/routes/demo/getting-started/02-loading-data/index.tsx" style={{ height: '6em' }}>
 ```tsx /routeLoader$/ /useDadJoke/
 import { component$ } from '@builder.io/qwik';
@@ -159,15 +159,15 @@ export default component$(() => {
 ```
 </CodeSandbox>
 
-## 3. Posting Data to Server
+## 3. Posting Data to the Server
 
-Previously we used `routeLoader$` to send data from the server to the client. We use [`routeAction$`](/docs/action/) to post (send) data from the client back to the server.
+Previously, we used `routeLoader$` to send data from the server to the client. To post (send) data from the client back to the server, we use [`routeAction$`](/docs/action/) .
 
-NOTE: `routeAction$` is the preferred way to send data to the server because it uses the browser native form API which works even if JavaScript is disabled.
+NOTE: `routeAction$` is the preferred way to send data to the server because it uses the browser native form API, which works even if JavaScript is disabled.
 
 To declare an action:
 
-1. Open `src/routes/joke/index.tsx` and add this code:
+1. In `src/routes/joke/index.tsx`, add this code:
 
 
 ```tsx /routeAction\$/
@@ -179,7 +179,7 @@ export const useJokeVoteAction = routeAction$((props) => {
 });
 ```
 
-2. Update the `export default` component to use the `useJokeVoteAction` hook. This is done by adding the `<Form>`.
+2. Update the `export default` component to use the `useJokeVoteAction` hook with `<Form>`.
 
 ```tsx {3,7-11} /favoriteJokeAction/
 export default component$(() => {
@@ -198,20 +198,22 @@ export default component$(() => {
 });
 ```
 
-3. Navigate to `http://127.0.0.1:5173/` to see the application running.
+3. Now on `http://localhost:5173/joke/`, the buttons display and if you click them, their value logs to the console.
 
-What does the above code do?
+Code explanation:
 
-- `routeAction$` is used to receive data.
+- `routeAction$` receives the data.
   - The function passed to `routeAction$` is invoked on the server whenever the form is posted.
-  - The `routeAction$` returns a use-hook (`useJokeVoteAction`) that can be used in the component post the form data.
+  - The `routeAction$` returns a use-hook, `useJokeVoteAction`, that you can use in the component to post the form data.
 - `Form` is a convenience component that wraps the browser's native `<form>` element.
 
 Things to note:
 
-- For validation see [zod validation](/docs/action/#zod-validation).
+- For validation, see [zod validation](/docs/action/#zod-validation).
 - The `routeAction$` works even if JavaScript is disabled.
-- If JavaScript is enabled the `Form` component will prevent the browser from posting the form and instead post the data using JavaScript and emulate the browser's native form behavior without full refresh.
+- If JavaScript is enabled, the `Form` component will prevent the browser from posting the form and instead post the data using JavaScript and emulate the browser's native form behavior without a full refresh.
+
+For reference, the complete code snippet for this section is as follows:
 
 <CodeSandbox src="/src/routes/demo/getting-started/03-posting-data/index.tsx" style={{ height: '8em' }}>
 ```tsx {21,25-29} /favoriteJokeAction/
@@ -252,15 +254,19 @@ export default component$(() => {
 
 ## 4. Modifying State
 
-Keeping track of the state and updating UI is core to what applications do. Qwik provides a `useSignal` hook to keep track of the application's state. To learn more see [state management](/docs/components/state/).
+Keeping track of the state and updating the UI is core to what applications do. Qwik provides a `useSignal` hook to keep track of the application's state. To learn more, see [state management](/docs/components/state/).
 
 To declare state:
 
-1. Declare the component's state using `useSignal()`.
+1. Import `useSignal` from `qwik`.
+   ```tsx /useSignal/
+   import { component$, useSignal } from "@builder.io/qwik";
+   ```
+2. Declare the component's state using `useSignal()`.
    ```tsx /useSignal/
    const isFavoriteSignal = useSignal(false);
    ```
-2. Add a button to the component that will modify the state.
+3. After the closing `Form` tag, add a button to the component to modify the state.
    ```tsx /isFavoriteSignal/
    <button 
     onClick$={() => {
@@ -270,7 +276,9 @@ To declare state:
    </button>
    ```
 
-NOTE: Clicking on the button will update the state and the UI will be updated.
+NOTE: Clicking on the button updates the state, which in turn updates the UI.
+
+For reference, the complete code snippet for this section is as follows:
 
 <CodeSandbox maxHeight={500} src="/src/routes/demo/getting-started/04-state/index.tsx" style={{ height: '10em' }}>
 ```tsx /isFavoriteSignal/
@@ -318,7 +326,7 @@ export default component$(() => {
 
 ## 5. Tasks and Invoking Server Code
 
-In Qwik, a [task](/docs/components/tasks/#usetask) is work that needs to happen when a state changes. (Similar to an "effect" in other frameworks.) In this example, we will use the task to invoke code on the server.
+In Qwik, a [task](/docs/components/tasks/#usetask) is work that needs to happen when a state changes. (This is similar to an "effect" in other frameworks.) In this example, we use the task to invoke code on the server.
 
 1. Create a new task that tracks the `isFavoriteSignal` state:
    ```tsx /useTask\$/
@@ -350,10 +358,12 @@ In Qwik, a [task](/docs/components/tasks/#usetask) is work that needs to happen
 
 NOTE:
 
-- Notice that the body of `useTask$` is executed on both the server and the client (isomorphic).
-- On SSR server prints `FAVORITE (isomorphic) false` and `FAVORITE (server) false`.
+- The body of `useTask$` is executed on both the server and the client (isomorphic).
+- On SSR, the server prints `FAVORITE (isomorphic) false` and `FAVORITE (server) false`.
 - When the user interacts with favorite, the client prints `FAVORITE (isomorphic) true` and the server prints `FAVORITE (server) true`.
 
+For reference, the complete code snippet for this section is as follows:
+
 <CodeSandbox maxHeight={500} src="/src/routes/demo/getting-started/05-tasks/index.tsx" style={{ height: '10em' }}>
 ```tsx {28-34}
 import { component$, useSignal, useTask$ } from '@builder.io/qwik';
@@ -436,12 +446,14 @@ To add styles:
    useStylesScoped$(STYLES);
    ```
 
-NOTE:
+Code explanation:
 
 - The `?inline` query parameter tells Vite to inline the styles into the component.
 - The `useStylesScoped$` call tells Qwik to associate the styles with the component only (scoping).
 - Styles are only loaded if they are not already inlined as part of SSR and only for the first component.
 
+For reference, the complete code snippet for this section is as follows:
+
 <CodeSandbox maxHeight={500} src="/src/routes/demo/getting-started/06-styling/index.tsx" style={{ height: '10em' }}>
 ```tsx /useStylesScoped\$/
 import {
@@ -506,14 +518,14 @@ export default component$(() => {
 
 ## 7. Preview
 
-We build a very simple application that gave you an overview of key Qwik concepts and API. The application is running in dev mode, which uses hot-module-reloading (HMR) to continuously update the application while changing the code.
+We built a minimal application that gave you an overview of key Qwik concepts and API. The application is running in dev mode, which uses hot-module-reloading (HMR) to continuously update the application while changing the code.
 
 While in dev mode:
 
 - Each file is loaded individually, which may cause waterfalls in the network tab.
 - There is no speculative loading of bundles, so there may be a delay on the first interaction.
 
-Let's create a production build to see how the application will be delivered to the user and how the above is fixed.
+Let's create a production build that eliminates these issues.
 
 To create a preview build:
 
@@ -526,10 +538,10 @@ NOTE:
 
 ## Review
 
-Congratulations! You have made it through getting started. This overview is intentionally short to get you familiarized with different parts of Qwik. We recommended that you deep dive into the above concepts to learn more. Here are some key takeaways:
-
+Congratulations! You've learned a lot about Qwik! 
+For more on just how much you can achieve with Qwik, we recommend reading the dedicated docs on each of the topics touched on in this tutorial:
 
-- [Project structure](/docs/(qwikcity)/project-structure/index.mdx)
+- [Project structure](/docs/(qwikcity)/project-structure/index.mdx):
 - [Directory-based](/docs/(qwikcity)/routing/index.mdx) routing
 - [Component](/docs/(qwik)/components/overview/index.mdx)
 - [Route loaders](/docs/(qwikcity)/route-loader/index.mdx)
