[Docs] Fix up caching docs as per user feedback

[ppiegaze]

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?

• Yes

Have you read the Code of Conduct?

• Yes

[sid-geospoc]

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]

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]

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]

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]

Added to planned work for docs team.

[10sharmashivam]

Hey,

I would like to work on this issue. I’ll focus on simplifying the existing caching documentation to make it more accessible for a wider audience, especially those who might not be familiar with advanced technical terms.

I will be:

1.	Simplifying Technical Terms: I will replace complex or technical terms (e.g., “task signature,” “cache_serialize”, "cache_ignore_input_vars") with simpler explanations and real-world examples to improve readability.
2.	Restructuring for Clarity: I’ll ensure the structure of the documentation flows logically, making it easier for users to follow. This includes improving section titles and breaking down longer explanations into more digestible parts.
3.	Short Video Demo: I can also create a short 1-2 minute video that provides a brief overview of caching and shows how to enable/disable it in Flyte. This would help users quickly grasp the concept. (If required).

Since simplifying documentation can be subjective, I’m open to feedback and suggestions to ensure the changes are helpful for the community.

Thanks! #take

[10sharmashivam]

Hi @neverett @ppiegaze, I submitted my PR yesterday for the assigned issue, and I wanted to follow up on it.

Also, While reviewing the documentation again, I got a question: Are checkpoints and targets part of Flyte’s caching mechanism? If they are, I think adding them would be beneficial in the caching documentation.

[davidmirror-ops]

While reviewing the documentation again, I got a question: Are checkpoints and targets part of Flyte’s caching mechanism?

I think checkpoints are more about preserving task state than memoizing execution results, as it is in caching. And not sure about "targets", not familiar with that concept in Flyte.

I think a good diagram would be helpful for this document.

Thanks!

[10sharmashivam]

I think a good diagram would be helpful for this document.

Thanks for the clarification on checkpoints, it helped clear things up. And I would try to create a Data flow diagram for Caching, and add it to flyteorg/static-resources (I believe this is the appropriate location for storing PNG files that can be linked in the documentation—please let me know if that’s correct).

And once that is approved and merged, will use its raw github user content link to add to caching's documentation.

[eapolinario]

And I would try to create a Data flow diagram for Caching, and add it to flyteorg/static-resources (I believe this is the appropriate location for storing PNG files that can be linked in the documentation—please let me know if that’s correct).

@10sharmashivam , are you working on this diagram?

[10sharmashivam]

Hi @eapolinario, Since the initial PR was merged, I haven’t made further progress on the diagram. However, if there is still value in adding it, I’d be happy to pick it up. Let me know how you’d like to proceed! and please let me know, the correct location for hosting this diagram.

[davidmirror-ops]

@10sharmashivam I think visual learners always appreciate a good diagram. Feel free to push it to static-resources :)