search

flyteorg / flyte

Scalable and flexible workflow orchestration platform that seamlessly unifies data, ML and analytics stacks.
https://flyte.org
Apache License 2.0
5.43k stars 581 forks source link

[Docs] Fix up caching docs as per user feedback #3249

Open ppiegaze opened 1 year ago

ppiegaze commented 1 year ago

Description

In this Slack thread we find the following advice (we should act on it):

Niels Bantilan @Sidharth (Sid) yes our flyte.org website revamp (coming soon!) should feature caching a lot more prominently. Out of curiosity, do you find the current docs on caching clear and understandable?

Sidharth(Sid) 18 hours ago I feel it has everything a person needs to understand Caching, but it needs a thorough read, maybe even a few times for a complete new comer to workflow tools. Also, terms related to caching such as "task Signature" could be simpler in my opinion. For example "Any changes to task Function". Prefect V1 docs for caching - https://docs-v1.prefect.io/core/concepts/persistence.html#output-caching-based-on-a-file-target Its pretty old, but has similar concepts explained in simple sentences. Im just sharing it so that I can show you what kind of understanding fits a crowd who are new to these tools. But I do wish the above prefect page to be more technical. Closer to flyte's way of explaining. Basically a middle ground will be nice. Also in Flyte current stable docs, I would wish for more details on "local cache storage" and "remote cache storage". The above prefect v1 doc gives some insight to it.

Are you sure this issue hasn't been raised already?

Have you read the Code of Conduct?

sid-geospoc commented 1 year ago

Few more points apart from those I had mentioned in thread -

  1. the 14min video part of the current stable docs is too long. A short 1 or 2 min video that goes through an example would be great. The video should leave enough room for thought, that the user then reads the technical docs to get complete picture.
  2. The new example in video could be some data science specific cache usage, and if possible, cross workflow caching usage, to show the true potential of caching in a DS/ML scenario.
  3. Both local and remote cache usage would be great, including registering of files.

The reason I said, in point 1, that the video should leave room for thought, is because I believe, after going through the current stable docs, that the technical writing of the docs is so good that it seems like its teaching good Python and K8 concepts along with Flyte's DSL. Atleast that's my view.

Thanks @ppiegaze for creating this thread.

sid-geospoc commented 1 year ago

Finally one small detail which could be changed is the "browser tab icon" ie., Favicon, for Flyte Docs and Flyte UI. This helps when multiple flyte sites such as Blogs, Docs, and UI is opened up in a browser, along with multiple other tabs. :)

github-actions[bot] commented 11 months ago

Hello 👋, This issue has been inactive for over 9 months. To help maintain a clean and focused backlog, we'll be marking this issue as stale and will close the issue if we detect no activity in the next 7 days. Thank you for your contribution and understanding! 🙏

github-actions[bot] commented 10 months ago

Hello 👋, This issue has been inactive for over 9 months and hasn't received any updates since it was marked as stale. We'll be closing this issue for now, but if you believe this issue is still relevant, please feel free to reopen it. Thank you for your contribution and understanding! 🙏

neverett commented 9 months ago

Added to planned work for docs team.