TFX documentation experience

[Sascha Heyer]

Hi TFX Team and Community, 

I want to share with you my user experience with the TFX documentation. 
Happy to start a joint force to improve the experience if the majority agrees with the following UX flow. 

What I was looking for?

• The Resolver component has multiple strategies. I wanted an overview of all possible strategies. 

Approach

• Go to https://www.tensorflow.org/tfx/api_overview 👍
• Search for resolver 👍
• Look for Resolver component results. Unfortunately, there is no way to filter only TFX related results.  👎
  
  
• Searching for Resolver TFX solves this but a filter would be great especially with an increasing number of TF libraries 
• With the adapted search query the component is returned unfortunately the first result is the deprecated component 👎. The fifth component is the correct one I was looking for
• Jumping directly onto that page to hopefully find an answer to my question: What kind of resolver strategies (strategy_class) are supported? Unfortunately, there is no overview on this page. 👎
  https://www.tensorflow.org/tfx/api_docs/python/tfx/dsl/components/common/resolver/Resolver
  
• Though there is an example, so I know there is at least a latest_artifacts_strategy.LatestArtifactsStrategy 👍
• Continue my journey to find all possible Strategies 👎
• At the top, there is a section that links to the https://www.tensorflow.org/tfx/api_docs/python/tfx/dsl/components/common/resolver/ResolverStrategy 
  This page again does not contain an overview of all possible ResolverStrategies 👎
  
• Continue my journey to find all possible Strategies 👎
• This page mentions resolver strategy subclasses but does not list them 👎
• Ok I know there is at least a LatestArtifactsStrategy, so I take this and search for it, hoping I can find other strategies that way. There is one result which only links to the Resolver component page again. 👎
  
  
  

This is honest feedback and meant as feedback to improve our TensorFlow documentation. This is by no means meant bad. 

To summarize 

• It would massively improve our documentation to showcase possible options and classes directly where we use them. Like in our case the Strategies. 
• The component ResolverNode is deprecated and links to Resolver but it seems there is still a lot of information missing. 

Best regards
Sascha

[Sascha Heyer]

Appendix:
I am aware that this specific component got deprecated 16 days ago. 
But I truly believe the documentation needs to go through the same quality requirements like production code does. 

[Irene Giannoumis]

I am sorry for your experience, I have created an internal bug to review this, adding @Ruoyu Liu for Resolver guidance

--
You received this message because you are subscribed to the Google Groups "TensorFlow Extended (TFX)" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tfx+uns...@tensorflow.org.
To view this discussion on the web visit https://groups.google.com/a/tensorflow.org/d/msgid/tfx/8fc4f4d4-be0e-4c32-9933-8d04853cc375n%40tensorflow.org.

[Adam Wood]

ruoyu@
Would the (long since in progress, but ignored by both of us) ResolverNode guide cover this? 

What is the deprecation story for the Resolver component?

Adam Michael Wood |

Technical Writer, TensorFlow |

adam...@google.com |

617-653-6570

I am a 60% Googler. (Also a parent in a pandemic.)

Please schedule meetings for Mondays or Wednesdays whenever possible.

(I can also take meetings at or after 8pm most nights if it is convenient for you.)

Working hours:
Monday: All day
Wednesday: All day
Tue, Thur, Fri: 9a-12p

Feel free to bug me via DM at any time for things you need.

To view this discussion on the web visit https://groups.google.com/a/tensorflow.org/d/msgid/tfx/CADGZekoCh9qWVTNsNsnF7jZcnpwjAA0os6LTFjO2cu%2Bc5PLr0Q%40mail.gmail.com.

[Adam Wood]

Okay - I'll move this Resolver article up in my priorities and talk to Ruoyu to hammer out technical content details.

Adam Michael Wood |

Technical Writer, TensorFlow |

adam...@google.com |

617-653-6570

I am a 60% Googler. (Also a parent in a pandemic.)

Please schedule meetings for Mondays or Wednesdays whenever possible.

(I can also take meetings at or after 8pm most nights if it is convenient for you.)

Working hours:
Monday: All day
Wednesday: All day
Tue, Thur, Fri: 9a-12p

Feel free to bug me via DM at any time for things you need.

On Thu, Feb 25, 2021 at 8:53 AM Ruoyu Liu <ru...@google.com> wrote:

Re Adam: Yes the ResolverNode guide you are working on should be able to cover this. However, now it should be referred to as `Resolver` after recent renaming.

Re Sascha: Our plan is to have a dedicated guide for people to (1) use Resolver during pipeline authoring time using a couple of default ResolverStrategy classes; and (2) being able to create their own definition of ResolverStrategy if they want to handle the packaging and plug into their pipeline.

--

Best,

Ruoyu

[Sascha Heyer]

Hi Adam,

@Irene Thanks a lot for your very quick response

@Adam a dedicated guide sounds amazing. 
Let me know if there is any way I can support you on that.

Appreciate the work you all doing for TFX, I am a great believer in this product. 

Best regards
Sascha

[Sascha Heyer]

Hi Adam,

Hi Irene,

Hi Ruoyu,

is there a place where I can find all existing strategies?
Can be either code or documentation doesn't matter. 

Best regards
Sascha