Please document expected results, context for common user actions

[RickJWagner]

[kind/Documentation]

What did you find missing in the documentation?

A clear explanation of what the user should expect when common actions are taken. As an example, 'push'.

• What is being pushed
• Which actions should be occuring in the K8S namespace as a result of 'push'
• Which K8S artifacts should be expected to appear/be manipulated? What state should they be in at the successful end of 'push'?
• What clues might be seen if something has gone wrong with 'push'? What kinds of remedies are available?

Please repeat for the most common actions.

What is the relevance of it?

Users are confused by Odo, it seems a 'black box' that is supposed to do things. (This would be fine if it were totally reliable, but this is sadly not the case. When something fails, the user is given very little information about what has happened/should have happened/ the state of their namespace/ etc.)

[cdrage]

Hi @RickJWagner

When you're referring to the missing documentation, I'm assuming it's from our docs on GitHub or odo --help ?

We have created a lot more docs that will soon be published on the official OpenShift site: https://docs.okd.io (which will be soon-ish)

[RickJWagner]

Hi @cdrage
Thanks for your work on docs. (As a support engineer, I can't stress how important good documentation is. It prevents unnecessary tickets from opening, it helps solve issues, it makes a good product become a great one. Doc writing is one of the most important steps in software development!)
My ask is for some good reference material. ('odo --help' is probably not the right place for such doc). Please let me know when the odo doc is live on docs.odk.io, I'll be glad to give it a look and offer opinions.
Thanks again for the work on docs. It is truly a vital component.

[cdrage]

Hi @RickJWagner ! The docs are now live (see the new README: https://github.com/openshift/odo/blob/master/README.adoc)

I realize I never answered your questions, so here goes:

What is being pushed

From odo push we show what's being pushed by indicating what code is being pushed and where exactly it's coming from (git, local folder, etc)

Which actions should be occurring in the K8S namespace as a result of 'push'

This we need to be more clear.. for example, we do not output that we are creating a new project and we should. However, we do hide all the other details on purpose (that we're deploying deployment config, volumes, etc..). Do you find that you'd like more information on what's being pushed?

Which K8S artifacts should be expected to appear/be manipulated? What state should they be in at the successful end of 'push'?

I agree that we need to elaborate more on this... what we are actually deploying. Since it's multiple containers, volumes as well as deployment config

What clues might be seen if something has gone wrong with 'push'? What kinds of remedies are available?

** You can use odo log to see what has gone wrong. However, it will fail anyways and output the error if you use odo push **

Let me know what you think of the responses and what you agree / disagree with. Your feedback is valuable.

[RickJWagner]

Hi @cdrage,
Thank you for your efforts here. I think Odo has great potential, and good docs will help it reach that potential. Thank you!
It is my opinion that we need to provide some reference material that the user can access if they have a need for detailed information about what Odo has done for them.
Wording that a different way: Odo is a nice, easy-to-use abstraction that simplifies Kubernetes development. (This is awesome!) But we need to have some layer available (perhaps in documentation, perhaps in verbose Odo logs) that can tell the user exactly what Odo has done for them. This is important:

• Because developers are going to want to learn more about the underlying K8S constructs. It's in the nature of the developer, they will not be happy with a tool that simplifies everything-- they want to know the underlying details, even if they have to dig for this information in an out-of-the-way place. To the developer, what really matters is knowing what's happened in K8S.
• The developer will need to know what K8S changes have been made so they can later clean it up. Say the developer has followed the "Deploying your first application" example in the README. That's great! After the developer has deployed that first application, they will next play with it for 5 minutes and then will want to clean it up, so nobody sees their 'hello world' tracks. They will need to know which K8S artifacts have been made for them, so they can go out to K8S and delete the Pods, Services, Config Maps, Roles, etc-- everything that Odo did. These are not all in one neat place, so it's important we have some way for the developer to understand what Odo did. (Otherwise there'll be some embarassing cruft left on OpenShift, and nobody will be able to know it's really garbage and can be deleted. This will eventually become a problem on OpenShift/K8S.)
• So the request is to give the user this important feature. They have to be able to look somewhere to see 'when I do X on odo, this causes Y on OpenShift'.
  Thanks again for your work!
  Rick

[kadel]

@RickJWagner This makes sense, thank you for this issue. This is something that we really need, and we have never properly captured it. It is not the first time this came up in the discussion.

@cdrage one of the common questions that I get from people is how odo works. We don't answer this question in our documentation and we should.
Our documentation should have at least a high-level overview of how odo works like:

• how we setup components
• why and how odo uses SupervisorD and initContainer
• how we use and interact with s2i build images

Currently, the only way to answer those questions is to go through the odo source code :-(
Such documentation will not be only helpful for end-users, but also for us. I have a suspicion that even people working on odo are sometimes not so sure how odo works.

Writing this documentation will require knowledge of odo internals. Not sure if it makes sense for the docs team to write this. It might be better for someone from odo developers to start with this and work on it together with the docs team. What do you think @boczkowska ?

[yhontyk]

Added expanded documentation on odo architecture. Hopefully, it covers at least some of the weaker points in docs: openshift/openshift-docs#18490

[Preeticp]

@kadel @cdrage @girishramnani can we consider this issue to be done and close this issue?

[cdrage]

@Preeticp I think so.

Does https://docs.openshift.com/container-platform/4.2/cli_reference/openshift_developer_cli/odo-architecture.html help @RickJWagner ?

[Preeticp]

Hi @RickJWagner, do you think the docs here: https://docs.openshift.com/container-platform/4.2/cli_reference/openshift_developer_cli/odo-architecture.html help resolve this issue? If yes, can we close this issue? Thank you.

[RickJWagner]

Hi @Preeticp,
(With apologies to @cdrage, I missed the 10 Feb inquiry).
Yes, thank you for these docs improvements. This goes a long way to explaining what Odo is doing. Thank you, thank you, thank you.
I'll close this issue tracker.

[Preeticp]

You are most welcome @RickJWagner. Just wanted to add, your feedback is greatly appreciated, it helps make our docs better.