griptape-ai / griptape-trade-school

Griptape Trade School mkdocs
4 stars 5 forks source link

Shotgrid Course Feedback (includes typos, grammar, and suggestions) for first four modules #36

Closed SavagePencil closed 11 months ago

SavagePencil commented 11 months ago

Describe the bug Objective: there are a number of typos and grammar errors Subjective: there are opportunities to consider to improve the readability and flow of the course.

To Reproduce Steps to reproduce the behavior:

  1. Go to https://learn.griptape.ai/dev/courses/shotgrid-client/
  2. Start reading!

Expected behavior

Objective Fixes

Autodesk ShotGrid - Signup

  1. "built in" -> "built-in"

Understanding Tools - DateTime

  1. "code in it's entirety" -> "code in its entirety"
  2. "It recognizes the need to use one of activities" -> one of its activities
  3. "about how tools are implement" -> about how tools are implemented
  4. "Hover over DateTime and choose Ctrl+Click (Cmd+Click on Mac)." one doesn't choose Cmd+Click, that's the shortcut. They choose...what is it, Go To Definition? Something like that.
  5. "And each method has it's associated activity." -> its
  6. "Simply put, the excpet block" -> except
  7. "often fixing it's own mistake" -> its
  8. "They are like a checlist for data" -> checklist
  9. "our app in it's current state" -> its

Subjective Fixes

Introduction

  1. Stress that the reader will be generating a Griptape Tool and why they would want to. For example, instead of "Throughout the course, you'll gain practical insights into constructing custom tools for specific activities. Our sessions will revolve around creating a Autodesk ShotGrid client tool as a practical example." you could say "At the end of this course, you will have working Python code for a Griptape Tool that enables a Griptape Agent to invoke capabilities from Autodesk Shotgrid." then give a concrete example of what the customer can do and what the results will be. This will drive home why this course rules.
  2. "a unique interest in harnessing the power of Griptape Tools" <- I don't have a unique interest, but I am eager for you to show me why I should have one
  3. Who this course is for: consider this a job application where you're offering what I have to have (intermediate Python) vs. what I could have or what you want me to have (pipeline experience).
  4. Open Q: you use "capital T" Tools when it's a Griptape Tool, but "lowercase T" tools when not. Worth a consistency pass? May look weird if it's always capital T Tools, but might also stress that it's an important noun.
  5. Is VS.Code really that useful of a resource :) ?

Setup

  1. The prerequisites here feel awfully similar to the ones in the Introduction. Can we reduce/consolidate?

Autodesk ShotGrid - Signup

  1. Consider putting the caveat box for signup process up earlier, so somebody hasn't clicked through only to find out it's all different.
  2. Could we move DateTime to earlier? Right now it feels like we go through all these steps to setup Shotgrid but then we jump over to Tools. Would it feel less jarring if we knew what a Tool was before doing a detour to Shotgrid?

Understanding Tools - DateTime

  1. In the Overview, you talk about Tools but not what they are or why we need them. "When an Agent needs to do something that the LLM doesn't offer, Griptape empowers the Agent with Tools to solve these problems" or somethin'
  2. Would you be comfortable skipping the babysteps Python coding and going straight to "Here's the code in its entirety:"? Are we confident the customer has gone through these steps already?
  3. "Learn more in the documentation." <- oof that's brutal
  4. "often fixing its own mistake" <- this sounds like it was Griptape's mistake, but put blame where it belongs!
  5. "Griptape Tools allow you to add functionality that Griptape structures (Agents, Pipelines, Workflows) can use." <- consistency on nouns; should Structures be capitalized?
  6. "For more information on the DateTime tool, you can visit the DateTime Tool Documentation." <- suggest you put this later, otherwise it may be a distracting click
  7. "Adding a tool is a relatively straightforward process." <- consider zapping adverbs that don't materially impact the message. I do a Cmd+F and search for "ly" as a start.
  8. As a reader, I don't fully understand the implications or benefits for off_prompt based on your description. Why do I want to offer those things to the LLM? Could that be bad?
  9. "Chain-of-thought" <- what's consistency here? "Chain-of -Thought?"
  10. For methods and activities, suggest you make it clear what they afford before saying what they are. "Methods define the actions that the Tool can perform. They are implemented as Python functions in the class." and "Activities tell the LLM what the action does and when it might want to use it. They are implemented as a decorator above the Python method."
  11. Suggest you bring the code for DateTime (or maybe one method/activity definition) up above methods and activities so it's more clearly linked conceptually.

Screenshots N/A

Desktop (please complete the following information):

Smartphone (please complete the following information):

Additional context Add any other context about the problem here.

shhlife commented 11 months ago

Wonderful feedback, thank you! I'll address it right away!

shhlife commented 11 months ago

@SavagePencil

Open Q: you use "capital T" Tools when it's a Griptape Tool, but "lowercase T" tools when not. Worth a consistency pass? May look weird if it's always capital T Tools, but might also stress that it's an important noun.

Yeah, I felt that it was important to call out that Griptape Tools are special. I'm adding a link to the Griptape Tools documentation the first time I mention it - is that enough to warrant capitalizing them?

Autodesk ShotGrid - Signup

  1. Consider putting the caveat box for signup process up earlier, so somebody hasn't clicked through only to find out it's all different.
  2. Could we move DateTime to earlier? Right now it feels like we go through all these steps to setup Shotgrid but then we jump over to Tools. Would it feel less jarring if we knew what a Tool was before doing a detour to Shotgrid?

1 - where would you recommend we move it to? It's before the step-by-step guide starts..

2 - Yeah, I was waffling on this - I thought getting setup stuff out of the way earlier would allow people to "stay in the flow" of development better, but it does feel a bit strange to go from griptape to shotgrid to griptape to shotgrid. I'll change it and see how it feels!

shhlife commented 11 months ago

Would you be comfortable skipping the babysteps Python coding and going straight to "Here's the code in its entirety:"? Are we confident the customer has gone through these steps already?

I was thinking we could link to that - but I've had feedback from people who aren't as confident in Python that they really appreciate stepping through it like this.. it helps them understand why we're doing things the way we are.

SavagePencil commented 11 months ago

@SavagePencil

Open Q: you use "capital T" Tools when it's a Griptape Tool, but "lowercase T" tools when not. Worth a consistency pass? May look weird if it's always capital T Tools, but might also stress that it's an important noun.

Yeah, I felt that it was important to call out that Griptape Tools are special. I'm adding a link to the Griptape Tools documentation the first time I mention it - is that enough to warrant capitalizing them?

My inner-RPG nerd wants it capitalized everywhere, but then it's very visually distracting. I think setting a precedent of "first use is capitalized, thereafter not so" should be fine. But even then we may find it odd when we're referring to capital T Tools the Class vs. tools the term. NOW I AM THE WAFFLER.

Autodesk ShotGrid - Signup

  1. Consider putting the caveat box for signup process up earlier, so somebody hasn't clicked through only to find out it's all different. 1 - where would you recommend we move it to? It's before the step-by-step guide starts..

Maybe I was on an earlier version or more likely I was in another realm of time and space. Please ignore.

shhlife commented 11 months ago

hah! waffles are good. :)

I'll go through and over-index on Tool when referencing Griptape Tools - and if people call it out, I can waffle-back and uncapitalize :)

shhlife commented 11 months ago

sweet - I believe I've addressed all the notes! will close now- but please add more feedback as you have time! :)