Docs use the term "App", but this term is not defined

[steren]

See for example "Updating an Existing App".

The concept of "App" is not defined in Knative.

[steren]

I do not think our docs should introduce resources that are not Knative resources.

Knative introduces the concept of "Service" that can map to what our docs are calling "application" today.

[mchmarny]

I think we are splitting the hair here. From user perspective the things they develop and deploy and manage are apps and functions. We should not force them to use our API resource names to describe the constructs they are used to.... after all, Knative is suppose to be idiomatic.

@steren let me know if you disagree, otherwise I recommend we close this issue

[rgregg]

We're trying to meet the developers where they are today, which is using terms like apps and functions. We want to map concepts the Knative users are familiar with into the API terminology through the documentation, not to lead with the new API terminology.

I don't see this as something that will be confusing to the majority of the audience coming to Knative, but a good place for us to listen to feedback from the community to be sure.

[steren]

Consistency between docs and resource names is a target. Otherwise, this proves we have made a bad job picking these resource names (we picked "service" based on research and customer feedback, see knative/serving#412.)

I agree that we should use app and function, especially for getting started use cases.
However, when a docs page is supposed to apply to "services", it should use the resource name accordingly. Technically, I can apply what is captured in "Updating an existing app" to a function.

Feel free to close if you disagree.

[labadav]

I agree that we do need to define terms, and we do need to develop a glossary. But I also agree with Mark and Ryan here: "apps" are what developers are developing, so changing Apps to services would be straight up confusing.

Maybe we should change the scope of this issue to needing glossary definitions for Knative terms. I would argue that this should be a post Next issue.

[rgregg]

@steren I do think in general that's right, but the topic you linked to isn't using the Service resource, it's using route/configuration directly, so the title is accurate, it reflects updating something that is conceptually an application, and not a specific resource type.

[mchmarny]

Would renaming sample to updating-existing-deployment.md, changing header to Updating an Existing Deployment and replacing all instances in readme to deployment where that makes sense be a acceptable compromise here?

+1 on defining terms though, @labadav

[steren]

Do you have more data about what users define as an application? I hear many different definition.
I know that some users will say an app is equivalent to code that you deploy and that can handle paths (which maps your definition), but I also know others consider an app to be a collection of services, potentially including a database. And some others will tell you that an app also includes clients, like mobile clients...

@rgregg if you read the problem statement of knative/serving#412, it shows that even if you only manipulate Route and Config, you do this within the context of an "orange box" (that we ended up naming service).

[steren]

@mchmarny my comment was more global than this particular example. We should agree on principles about when it's OK to use "app" as a shortcut and when we should use the exact resource terminology.

[labadav]

Opened a separate issue for glossary of terms and added it to the post launch project: #170

[rgregg]

I've read that link @steren, and I know that we shared an architecture diagram and asked people what to label a part of the diagram. Service may be the best word for that part of the drawing, but service is a generic word (and so overloaded!). The more I've been using Knative the less I feel service is appropriate (the overload already means I have to type service.serving.knative.dev every time I want to use it with kubectl, which alone is enough to make me want to find a better word. I don't have a suggestion for an alternative though.

I see evidence that developers (and operators) approach the concept of "deploying code that runs in an environment" under many names, be it applications, apps, functions, services, micro-services, or widgets. OK, maybe not the last one. We didn't use apps to try and formalize that definition to a specific meaning. Instead, we used that term because developers use that term to describe something similar to what we're talking about. We want to meet developers where they are, rather than force specific terminology that means different things to different people.

If we hear additional feedback that we need to be more specific or that this language is confusing as developers approach Knative, I'm all for updating the docs. However, without that in place yet, there are more important things to be working on.

I'm going to close this issue, but will definitely be watching for this in the feedback to come. If anyone wants to reopen or open a new issue, please do so.

[steren]

Note that knative/serving#1588 should greatly help regarding the kubectl experience.