search

Azure / azure-sdk-for-net

This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.
MIT License
5.26k stars 4.61k forks source link

Form Recognizer: Naming for StartTraining: Supervised/Unsupervised #9970

Closed annelo-msft closed 4 years ago

annelo-msft commented 4 years ago

Regarding the naming of

Sometimes users just don't understand a concept and no amount of renaming will fix that. In such cases, it's often better to just "hide" one of the options so that the users are not forced to make decisions while they don't understand the concepts. And so, if they don't understand what "WithLabels" means, but they are forced to make a decision between these two methods, they will be less happy with the API.

I think it would be a mistake to hide the StartTrainingWithLabels() method. There’s a lot of work involved with setting up the training files needed in the blob container, so customers have to have some concept of what’s happening. Hopefully they would think – what is this “with labels” -- if I don’t know it must not be for me. Because there is a lot of work involved in creating a label file. So there’s a barrier to entry to the training methods – I wonder if we should seriously consider moving training into a separate API based on that ….people using the models for Analysis don’t necessarily need to know how they’re trained, although they do need to know the difference between the output of the model types, because they contain different things.

Something to keep in mind is that TrainWithLabels requires a lot of UI overhead that is not achievable using the SDK.

A much more typical scenario is that a user completes 100% of the labeled training operation from within a visual UX. The tool will assist the user in generating the required label files and preprocessed OCR files that "TrainWithLabels" requires

That might be a valid reason to hide or separate the TrainWithLabels operation/client.

There is really nothing stopping a misguided user from calling TrainWithModels vs Train since the API is the same (it's not like the user is providing the labels through the client request - they are expected to already exist on their blob container).

annelo-msft commented 4 years ago

@ctstone @mayurid @kristapratico @samvaity @jeremymeng

annelo-msft commented 4 years ago

Design prototyped. We can reopen this issue or create new ones from UX feedback. @mayurid