Redirect to upstream docs instructions are not clear for the end-users

camilamacedo86 commented 3 years ago

Bug Report

What did you do?

In many places of the SDK documentation, users are redirected to check the upstream docs, however, it has not been clarified to them why and that they could follow the same upstream instructions by replacing kubebuilder command with operator-sdk one. (E.g how they can know by checking the migration guide that they can use operator-sdk init instead of kubebuilder init as described there or in the multi-group setup that can use operator-sdk edit --multi-group instead of kubebuilder edit --multigroup)

PS.: SDK has tracked issues where the users say that they did not know about that as it was asked in the channels as well too.

What did you expect to see?

End-users are only looking to use the tool and they do not want really want to know deeper about the plugin ecosystem and how it works and etc. They will look for directly instructions to solve their needs. So, I'd expected in all places that we redirect users to the upstream docs small info such as:

"SDK and Kubebuilder are integrated projects. Check [here] the documentation in Kubebuilder which will describe how you will able to do N. Note that you should use operator-sdk instead of kubebuilder for all command-line instructions.

OR

"SDK and Kubebuilder are integrated projects. Check [here] the documentation in Kubebuilder to know how to configure your project to use the multi-group layout. Note that you should use operator-sdk edit instead of kubebuilder edit.

What did you see instead? Under which circumstances?

Look [here] the Kubebuilder docs.

estroz commented 3 years ago

Additionally, documenting that upstream docs use the CronJob GVK which should be replaced (mentally) with the Memcached GVK.

camilamacedo86 commented 3 years ago

Additionally, documenting that upstream docs use the CronJob GVK which should be replaced (mentally) with the Memcached GVK.

Our samples and mock tests and tutorials are all based on the Memcached example. In this way, imo;

For the purposes to describe how things work our tutorial is very smaller and hit the goal faster
I am afraid that the CronJob example in upstream does not make sense for Helm/Ansible and any other possible type which bring complexities for us such as: How we and users will be able to know that the same operation is achievable with the other language? How can we compare ansible/helm/go samples to check the diff if they are not equals/ How can we use a common doc if we have a diff example for each type? Could not it be confusing?
Then, change the tutorial means to change the samples and tests which shows a high effort. Then, what are the real advantages that we will have that justify this effort?

So, I'd like to suggest for we only address here the problem raise as we discussed in the bug triage meeting which means:

Check all place in the docs which are addressing the users for kubebuilder
Then, replace all of them which has kb instruction only (e.g kubebuilder init) at least by coping ad pasting their content in the sdk side and updating it accordingly.

IMO: Would more valuable we spend effort improving the sample tutorial by adding how to use a finalizer, how to work with status conditionals, how to implement the controller tests then just replace the example for cronjob in upstream which also shows not cover these points.

jmrodri commented 3 years ago

@camilamacedo86 PR #4676 does not actually address this issue. Having the FAQ is great but I think that's all we need.

camilamacedo86 commented 3 years ago

What do you think that we need to do here? What are your thoughts @jmrodri? Do you think that we should replicate the docs? The cons with that IMO is only that we need to keep maintained both. If we change nothing that we will need to change here as well.

jmrodri commented 3 years ago

What do you think that we need to do here? What are your thoughts @jmrodri? Do you think that we should replicate the docs? The cons with that IMO is only that we need to keep maintained both. If we change nothing that we will need to change here as well.

@camilamacedo86 This issue indicates that the users are confused when they are sent to kubebuilder docs from various places. The PR simply added FAQ links. It feels like if the issue is with the migration guide we need a page or a paragraph somewhere on the site that discusses kubebuilder etc.

How about we add something to the Overview sections?

Something like the following:

The motivations for the new layout are related to bringing more flexibility to users and part of the process to Integrating Kubebuilder and Operator SDK. Because of this integration you may be referred to the Kubebuilder documentation https://book.kubebuilder.io/ for more information about certain topics. When using this document just remember to replace $ kubebuilder <command> with $ operator-sdk <command>.

Having this in the overviews feels less awkward because we are already talking about Kubebuilder so it feels more natural to warn the user there.

camilamacedo86 commented 3 years ago

Hi @jmrodri,

I really like your suggestion and IMO the overview text added here much better than the text that we have now. So, done 👍

operator-framework / operator-sdk