Upload the tutorial for the FastAPI search bot #8314
Conversation
|
The following commit authors need to sign the Contributor License Agreement: Click the button to sign: |
Docs preview deploy❌ Docs preview deployment failed for commit ae0dca2: https://edgedb-docs-4wnp8zvfp-edgedb.vercel.app (Last updated: Feb 19, 2025, 19:35:08 UTC) |
|
I like the flow & style, but I feel we shouldn't mess with Google and beautiful soup and instead build this for some API. HN search API is one such option. We can look for some other publicly accessible search APIs. The HN one can be fun (and potentially we can make some stupid/fun demos). Another thing: please transform this into the new-style two-column tutorial. I've just reviewed Scott's PR and from it I now know that it's easier to assess the flow that way. |
Sure, will do. Still figuring out the whole RST business. |
There was a problem hiding this comment.
I'll leave a note here that I previously wrote for Scott's PR (by the way, I don't have particularly strong feelings about it. I don't think using "we" is wrong or worse, but we might try to adopt a more instructive tone by using "you").
A note on "we" vs "you": I noticed the quickstart switches between the two, which is generally not a wrong practice, but I was thinking we should stick to one.
"We" is great for creating personal connections between the user and the company, but it's sometimes unclear what "we" refers to - is it user+author, the company, or the tool? I saw another argument somewhere against "we" that "you're not sitting with the author".
For example, if there's "now, we'll create a function", it can be unclear whether "we will" means there's a Gel tool that does this or it's metaphorically "we". In most cases "we" don't do these things - user "you" does. Or "we will create a migration to apply this schema" can make total sense in the context but if someones loses the context, they can think "gel (we) will create a migration to apply this schema".
I would use "we" only for introductions or summaries - "we'll walk you through...", "we covered", "we have a template app for you to clone" - i.e. in places where it make sense to refer to us (authors/company). And for all instructions we can go with "you" - "make sure you have ...", "(you) clone our repo", for example:
We'll create a proper data model for our application in the next step
can be
We will show you how to create a proper data model for your application in the next step
or
In the next step, you will create a proper data model for your application.
Switching to "you" for instructions takes away some of this connection vibe, but can make it more straight to the point. FWIW, "let's make ..." is fine as is.
| In case you need installation instructions, take a look at the :ref:`Quickstart | ||
| <ref_quickstart>`. Once Gel CLI is present in your system, initialize the | ||
| project like this: |
There was a problem hiding this comment.
Now that's tricky. Since we'll have the quickstart as a more extended tutorial, should we have separate, short setup guides to refer people in cases like this one?
cc @scotttrinh
There was a problem hiding this comment.
We can point to a reference manual instead. Unless there're specific non-trivial considerations or instructions there, in which case I think there needs to be a short guide, sure.
| the schema. By convention established in the LLM space, each message is going to | ||
| have a role in addition to the message content itself. We can also get Gel to | ||
| automatically keep track of message's creation time by adding a property callled | ||
| ``timestamp`` and setting its :ref:`default value <ref_datamodel_props>` to the |
There was a problem hiding this comment.
Shouldn't it be created_at or created? Seem to be a more common way to name these things
There was a problem hiding this comment.
I guess it should. I'm honestly not super happy with the naming across the app right now - there're too many things named search-something, there's search_terms.query vs search_query (not the same thing) and so on. I'd like to rename everything in-bulk later, once all the major things are out of the way.
I've been loosely applying this stylistic guidance throughout the tutorial. So the way I frame this it's less of us giving instructions to the reader, and more of us and the reader doing a thing together, and them learning in the process. I think this makes the tutorial a little more engaging. And I think completing a tutorial should resemble the process of making a real app, which in turn isn't about piping a series of instruction together. |
deepbuzin
force-pushed
the
tutorial-fastapi-gelai
branch
3 times, most recently
from
b046459 to
bafcb18
Compare
Update code samples with diffs
replace openai dep with http, fix chat history handling
deepbuzin
force-pushed
the
tutorial-fastapi-gelai
branch
from
bafcb18 to
84b1720
Compare
No description provided.