Quickstart refinements #13244

billpalombi · 2024-05-04T02:37:08Z

I think we need to smooth out our quickstart. This is just a start.

netlify · 2024-05-04T02:37:25Z

✅ Deploy Preview for prefect-docs-preview ready!

Name	Link
🔨 Latest commit	`3220936`
🔍 Latest deploy log	https://app.netlify.com/sites/prefect-docs-preview/deploys/6636e14b3c0aef00086ea9ad
😎 Deploy Preview	https://deploy-preview-13244--prefect-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

zhen0

Thank you Bill for the quick updates. I've added a few suggestions. And we should fix the typo before releasing.

zhen0 · 2024-05-04T07:19:41Z

docs/getting-started/quickstart.md

-With Prefect, you can go from a Python script to a production-ready workflow that runs remotely in a few minutes.
-
-Let's get started!
+Prefect is a workflow orchestration platform for building data pipelines, background jobs, LLM Chains, and more. With Prefect, you can elevate a Python script into a scheduled, observable, resilient, remotely execuateble workflow in a few minutes. Let's get started!


Small typo in executable- sorry on mobile so I can't make a suggested change.

zhen0 · 2024-05-04T07:21:57Z

docs/getting-started/quickstart.md

 ```

-Let's make this script schedulable, observable, resilient, and capable of running anywhere.
+Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works. Let's make this script schedulable, observable, resilient, and capable of running anywhere.


Is the "let's make this" section still meant to be in here? It feels a little disjointed.

I think it's meant to be a transition from "you just have a script" to "look what Prefect can do for you". Is that transition improved by the suggested change added below?

zhen0 · 2024-05-04T07:22:59Z

docs/getting-started/quickstart.md


 ## Step 2: Connect to Prefect's API

-Much of Prefect's functionality is backed by an API.
-The easiest way to get started is to use the API hosted by Prefect:
+Much of Prefect's functionality is backed by an API. You can [host Prefect server](/guides/host/) yourself if you'd like, but the easiest way to get started is to use the API hosted by Prefect Cloud:


Does the mention of server here increase complexity?

I think this distracts from the flow. Perhaps we move the info about self-hosted instances to the Next steps section at the end of the quickstart?

Line 257 could easily be modified to include a mention of self-hosted instances.

zhen0 · 2024-05-04T07:26:12Z

docs/getting-started/quickstart.md

@@ -174,10 +170,9 @@ prefect work-pool create my-managed-pool --type prefect:managed
 You should see a message in the CLI that your work pool was created.
 Feel free to check out your new work pool on the **Work Pools** page in the UI.


Is this line helpful? I'd vote to remove it as it pulls the user away from the main focus.

Good question. I think we want to get the user checking out the UI at some point, but maybe not until they run the deployment.

Something I've been wondering. Can this entire workflow be completed in the UI or CLI? I think we should minimize the amount we ask people to bounce between the UI and CLI. One handoff is probably fine, multiple handoffs less so.

You could do it all in Python code + CLI. The UI is a core part of the product that I think we want folks interacting with. That said, I hear you on bouncing back and forth being distracting.

zhen0 · 2024-05-04T07:28:28Z

docs/getting-started/quickstart.md

@@ -192,13 +187,11 @@ if __name__ == "__main__":
        entrypoint="my_gh_workflow.py:repo_info",
    ).deploy(
        name="my-first-deployment",
-        work_pool_name="my-managed-pool",


Actually a content from line 186 - I suggest we point out more clearly that here they're using code we've stored in GitHub.

When I went through this quickstart for the first time, I was definitely confused about how GitHub fits into it. More clarification would be awesome.

discdiver

Thank you. Minor edits and notes.

discdiver · 2024-05-05T01:10:52Z

docs/getting-started/quickstart.md

-We can have Prefect Cloud run our flow code for us with a Prefect Managed work pool.
-
-Let's create a [Prefect Managed work pool](/guides/managed-execution/) so that Prefect can run our flows for us.
+Prefect refers to infrastructure that can run worflows as [work pools](/concepts/work-pools/). 


Suggested change

Prefect refers to infrastructure that can run worflows as [work pools](/concepts/work-pools/).

Prefect refers to infrastructure that can run workflows as a [work pool](/concepts/work-pools/).

discdiver · 2024-05-05T01:12:44Z

docs/getting-started/quickstart.md

-
-Let's create a [Prefect Managed work pool](/guides/managed-execution/) so that Prefect can run our flows for us.
+Prefect refers to infrastructure that can run worflows as [work pools](/concepts/work-pools/). 
+Prefect can orchestrate workflows that run remotely on many [types of infrastructure](/work-pools/#work-pool-types), but here we'll use a [Prefect Managed work pool](/guides/managed-execution/) so that Prefect can run this flow for us.


Suggested change

Prefect can orchestrate workflows that run remotely on many [types of infrastructure](/work-pools/#work-pool-types), but here we'll use a [Prefect Managed work pool](/guides/managed-execution/) so that Prefect can run this flow for us.

Prefect can orchestrate workflows that run remotely on many [types of infrastructure](/work-pools/#work-pool-types). We'll use a [Prefect Managed work pool](/guides/managed-execution/) so that Prefect can run this flow for us.

discdiver · 2024-05-05T01:16:51Z

docs/getting-started/quickstart.md

@@ -174,10 +170,9 @@ prefect work-pool create my-managed-pool --type prefect:managed
 You should see a message in the CLI that your work pool was created.
 Feel free to check out your new work pool on the **Work Pools** page in the UI.


Good question. I think we want to get the user checking out the UI at some point, but maybe not until they run the deployment.

discdiver · 2024-05-05T01:18:06Z

docs/getting-started/quickstart.md


 ## Step 2: Connect to Prefect's API

-Much of Prefect's functionality is backed by an API.
-The easiest way to get started is to use the API hosted by Prefect:
+Much of Prefect's functionality is backed by an API. You can [host Prefect server](/guides/host/) yourself if you'd like, but the easiest way to get started is to use the API hosted by Prefect Cloud:


Suggested change

Much of Prefect's functionality is backed by an API. You can [host Prefect server](/guides/host/) yourself if you'd like, but the easiest way to get started is to use the API hosted by Prefect Cloud:

Much of Prefect's functionality is backed by an API. You can [host a Prefect server instance](/guides/host/) yourself if you'd like, but the easiest way to get started is to use the API hosted by Prefect Cloud:

discdiver · 2024-05-05T01:19:05Z

docs/getting-started/quickstart.md

-With Prefect, you can go from a Python script to a production-ready workflow that runs remotely in a few minutes.
-
-Let's get started!
+Prefect is a workflow orchestration platform for building data pipelines, background jobs, LLM Chains, and more. With Prefect, you can elevate a Python script into a scheduled, observable, resilient, remotely execuateble workflow in a few minutes. Let's get started!


Suggested change

Prefect is a workflow orchestration platform for building data pipelines, background jobs, LLM Chains, and more. With Prefect, you can elevate a Python script into a scheduled, observable, resilient, remotely execuateble workflow in a few minutes. Let's get started!

Prefect is a workflow orchestration platform for building data pipelines, background jobs, LLM Chains, and more. With Prefect, you can elevate a Python script into a scheduled, observable, resilient, remotely executable workflow in a few minutes. Let's get started!

discdiver · 2024-05-05T01:21:32Z

docs/getting-started/quickstart.md

 ```

-Let's make this script schedulable, observable, resilient, and capable of running anywhere.
+Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works. Let's make this script schedulable, observable, resilient, and capable of running anywhere.


Suggested change

Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works. Let's make this script schedulable, observable, resilient, and capable of running anywhere.

Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works.

Now let's use Prefect to make this script schedulable, observable, resilient, and capable of running anywhere.

There's an extra leading space on line 53, but I think this helps to differentiate the setup from the next steps.

I might go a step further and encourage people to spin up an IDE to save them a step later when we ask them to run pip/python commands.

Suggested change

Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works. Let's make this script schedulable, observable, resilient, and capable of running anywhere.

Create a new project in your favorite IDE, and then copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works.

Now let's use Prefect to make this script schedulable, observable, resilient, and capable of running anywhere.

discdiver · 2024-05-05T01:22:05Z

docs/getting-started/quickstart.md

 ```

-Let's make this script schedulable, observable, resilient, and capable of running anywhere.
+Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works. Let's make this script schedulable, observable, resilient, and capable of running anywhere.


I think it's meant to be a transition from "you just have a script" to "look what Prefect can do for you". Is that transition improved by the suggested change added below?

discdiver · 2024-05-05T01:24:47Z

docs/getting-started/quickstart.md

@@ -192,13 +187,11 @@ if __name__ == "__main__":
        entrypoint="my_gh_workflow.py:repo_info",


Making the source a Prefect repo would be good.

djsauble · 2024-05-06T18:34:48Z

docs/getting-started/quickstart.md

 ```

-Let's make this script schedulable, observable, resilient, and capable of running anywhere.
+Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works. Let's make this script schedulable, observable, resilient, and capable of running anywhere.


There's an extra leading space on line 53, but I think this helps to differentiate the setup from the next steps.

I might go a step further and encourage people to spin up an IDE to save them a step later when we ask them to run pip/python commands.

Suggested change

Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works. Let's make this script schedulable, observable, resilient, and capable of running anywhere.

Create a new project in your favorite IDE, and then copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works.

Now let's use Prefect to make this script schedulable, observable, resilient, and capable of running anywhere.

djsauble · 2024-05-06T18:38:19Z

docs/getting-started/quickstart.md

-With Prefect, you can go from a Python script to a production-ready workflow that runs remotely in a few minutes.
-
-Let's get started!
+Prefect is a workflow orchestration platform for building data pipelines, background jobs, LLM Chains, and more. With Prefect, you can elevate a Python script into a scheduled, observable, resilient, remotely execuateble workflow in a few minutes. Let's get started!

 ## Setup


It's best to use task-based titles. For example, see https://developers.google.com/style/headings

Suggested change

## Setup

## Set up your environment

djsauble · 2024-05-06T18:43:36Z

docs/getting-started/quickstart.md


 ## Step 1: Install Prefect

+Make sure you have Python installed in a virtual environment. Then install Prefect:
+
 ```bash
 pip install -U prefect


I could go either way on this. People who care about virtual environments will tend to already know how to do this, but we can save some typing by putting those commands inline.

Suggested change

pip install -U prefect

# Set up a virtual environment

python -m venv env

source env/bin/activate

# Install Prefect

pip install -U prefect

djsauble · 2024-05-06T18:45:04Z

docs/getting-started/quickstart.md

 ```bash
 pip install -U prefect
 ```

-See the [install guide](/getting-started/installation/) for more detailed installation instructions, if needed.
+See the [install guide](/getting-started/installation/) for more detailed installation instructions.


Or maybe the virtual environment setup commands could go here.

djsauble · 2024-05-06T18:47:36Z

docs/getting-started/quickstart.md


 ## Step 2: Connect to Prefect's API

-Much of Prefect's functionality is backed by an API.
-The easiest way to get started is to use the API hosted by Prefect:
+Much of Prefect's functionality is backed by an API. You can [host Prefect server](/guides/host/) yourself if you'd like, but the easiest way to get started is to use the API hosted by Prefect Cloud:


I think this distracts from the flow. Perhaps we move the info about self-hosted instances to the Next steps section at the end of the quickstart?

Line 257 could easily be modified to include a mention of self-hosted instances.

djsauble · 2024-05-06T18:55:02Z

docs/getting-started/quickstart.md

@@ -100,27 +108,20 @@ def get_contributors(repo_info: dict):
    contributors = response.json()
    return contributors

-
 @flow(log_prints=True)


Suggested change

@flow(log_prints=True)

# This method is the flow entrypoint

@flow(log_prints=True)

djsauble · 2024-05-06T18:58:11Z

docs/getting-started/quickstart.md

@@ -130,7 +131,7 @@ python my_gh_workflow.py

 </div>

-Now when we run this script, Prefect will automatically track the state of the flow run and log the output where we can see it in the UI and CLI.
+Prefect will automatically track the state of the flow run and log the output where we can see it in the UI and CLI.


I don't think it's necessary to specify where the output appears, since it appears in all interfaces.

Suggested change

Prefect will automatically track the state of the flow run and log the output where we can see it in the UI and CLI.

Prefect will automatically track the state of the flow run and log the output.

djsauble · 2024-05-06T19:00:55Z

docs/getting-started/quickstart.md

@@ -174,10 +170,9 @@ prefect work-pool create my-managed-pool --type prefect:managed
 You should see a message in the CLI that your work pool was created.
 Feel free to check out your new work pool on the **Work Pools** page in the UI.


Something I've been wondering. Can this entire workflow be completed in the UI or CLI? I think we should minimize the amount we ask people to bounce between the UI and CLI. One handoff is probably fine, multiple handoffs less so.

djsauble · 2024-05-06T19:02:30Z

docs/getting-started/quickstart.md


-We have a flow function and we have a work pool where we can run our flow remotely.
-Let's package both of these things, along with the location for where to find our flow code, into a [deployment](/concepts/deployments/) so that we can schedule our workflow to run remotely.
+We now have a flow and a work pool where we can run it. Let's package both of these things, into a [deployment](/concepts/deployments/) so that we can run our workflow remotely.


Suggested change

We now have a flow and a work pool where we can run it. Let's package both of these things, into a [deployment](/concepts/deployments/) so that we can run our workflow remotely.

We now have a flow and a work pool where we can run it. Let's package them into a [deployment](/concepts/deployments/) so that we can run our workflow remotely.

djsauble · 2024-05-06T19:04:01Z

docs/getting-started/quickstart.md

@@ -192,13 +187,11 @@ if __name__ == "__main__":
        entrypoint="my_gh_workflow.py:repo_info",
    ).deploy(
        name="my-first-deployment",
-        work_pool_name="my-managed-pool",


When I went through this quickstart for the first time, I was definitely confused about how GitHub fits into it. More clarification would be awesome.

github-actions · 2024-05-20T20:01:11Z

This pull request is stale because it has been open 14 days with no activity. To keep this pull request open remove stale label or comment.

Quickstart refinements

6ca6d61

I think we need to smooth out our quickstart. This is just a start.

aaazzam approved these changes May 4, 2024

View reviewed changes

zhen0 reviewed May 4, 2024

View reviewed changes

discdiver reviewed May 5, 2024

View reviewed changes

discdiver self-requested a review May 5, 2024 01:29

Update quickstart.md

3220936

djsauble reviewed May 6, 2024

View reviewed changes

github-actions bot added the status:stale This may not be relevant anymore label May 20, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Quickstart refinements #13244

Quickstart refinements #13244

billpalombi commented May 4, 2024

netlify bot commented May 4, 2024 •

edited

zhen0 left a comment

zhen0 May 4, 2024

zhen0 May 4, 2024

discdiver May 5, 2024

zhen0 May 4, 2024

djsauble May 6, 2024 •

edited

zhen0 May 4, 2024

discdiver May 5, 2024

djsauble May 6, 2024

discdiver May 6, 2024

zhen0 May 4, 2024

djsauble May 6, 2024

discdiver left a comment

discdiver May 5, 2024

discdiver May 5, 2024

discdiver May 5, 2024

discdiver May 5, 2024

discdiver May 5, 2024

discdiver May 5, 2024

djsauble May 6, 2024

discdiver May 5, 2024

discdiver May 5, 2024

djsauble May 6, 2024

djsauble May 6, 2024

djsauble May 6, 2024

djsauble May 6, 2024

djsauble May 6, 2024 •

edited

djsauble May 6, 2024

djsauble May 6, 2024

djsauble May 6, 2024

djsauble May 6, 2024

djsauble May 6, 2024

github-actions bot commented May 20, 2024

		@@ -174,10 +170,9 @@ prefect work-pool create my-managed-pool --type prefect:managed
		You should see a message in the CLI that your work pool was created.
		Feel free to check out your new work pool on the Work Pools page in the UI.

	Prefect refers to infrastructure that can run worflows as [work pools](/concepts/work-pools/).
	Prefect refers to infrastructure that can run workflows as a [work pool](/concepts/work-pools/).

	Prefect can orchestrate workflows that run remotely on many [types of infrastructure](/work-pools/#work-pool-types), but here we'll use a [Prefect Managed work pool](/guides/managed-execution/) so that Prefect can run this flow for us.
	Prefect can orchestrate workflows that run remotely on many [types of infrastructure](/work-pools/#work-pool-types). We'll use a [Prefect Managed work pool](/guides/managed-execution/) so that Prefect can run this flow for us.

	Much of Prefect's functionality is backed by an API. You can [host Prefect server](/guides/host/) yourself if you'd like, but the easiest way to get started is to use the API hosted by Prefect Cloud:
	Much of Prefect's functionality is backed by an API. You can [host a Prefect server instance](/guides/host/) yourself if you'd like, but the easiest way to get started is to use the API hosted by Prefect Cloud:

	Prefect is a workflow orchestration platform for building data pipelines, background jobs, LLM Chains, and more. With Prefect, you can elevate a Python script into a scheduled, observable, resilient, remotely execuateble workflow in a few minutes. Let's get started!
	Prefect is a workflow orchestration platform for building data pipelines, background jobs, LLM Chains, and more. With Prefect, you can elevate a Python script into a scheduled, observable, resilient, remotely executable workflow in a few minutes. Let's get started!

-Copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works. Let's make this script schedulable, observable, resilient, and capable of running anywhere.
+Create a new project in your favorite IDE, and then copy this script into a file named `my_gh_workflow.py`. Run it locally to ensure your Python environment works.
+Now let's use Prefect to make this script schedulable, observable, resilient, and capable of running anywhere.

		@@ -192,13 +187,11 @@ if __name__ == "__main__":
		entrypoint="my_gh_workflow.py:repo_info",

-pip install -U prefect
+# Set up a virtual environment
+python -m venv env
+source env/bin/activate
+# Install Prefect
+pip install -U prefect

	@flow(log_prints=True)
	# This method is the flow entrypoint
	@flow(log_prints=True)

	Prefect will automatically track the state of the flow run and log the output where we can see it in the UI and CLI.
	Prefect will automatically track the state of the flow run and log the output.

	We now have a flow and a work pool where we can run it. Let's package both of these things, into a [deployment](/concepts/deployments/) so that we can run our workflow remotely.
	We now have a flow and a work pool where we can run it. Let's package them into a [deployment](/concepts/deployments/) so that we can run our workflow remotely.

Quickstart refinements #13244

Are you sure you want to change the base?

Quickstart refinements #13244

Conversation

billpalombi commented May 4, 2024

netlify bot commented May 4, 2024 • edited

✅ Deploy Preview for prefect-docs-preview ready!

zhen0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djsauble May 6, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

discdiver left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

djsauble May 6, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented May 20, 2024

netlify bot commented May 4, 2024 •

edited

djsauble May 6, 2024 •

edited

djsauble May 6, 2024 •

edited