knative
Consider using functions for developer tutorial
Please consider reviewing the proposal to highlight Functions in the developer tutorial.
https://docs.google.com/document/d/1wBpBA76nfgqoN6vKje7g1n7milB8l5gQZfuE49_teAk/edit?usp=sharing
Let's get input from the steering committee on this as @dprotaso mentioned on the TOC call. I think it would be good to have a consensus about the marketing direction of Knative once functions is added and where different components fall in terms of user-facing importance.
Let's get input from the steering committee on this as @dprotaso mentioned on the TOC call. I think it would be good to have a consensus about the marketing direction of Knative once functions is added and where different components fall in terms of user-facing importance.
Sounds good. We did not have a SC quorum today, but we should have it on the agenda next week. /cc @knative/steering-committee
I like the proposal, but I would still love to see the "Hello World" sample and deploy. My preference will be to be able to deploy a small service like the "hello world", then move to try out functions and hopefully that part from the proposal would show how to use it with cloud events.
Some background: In recognition that Functions is one of the main components to Knative, it was promoted from Sandbox to Core. The Functions Task Force under the CLI Working Group was promoted to be a Working Group under the Knative TOC. The git repository for func remains in knative-sandbox, and it is up to the WG to decide when to move it to the knative git organization.
With my Knative Steering Committee hat on, here are some recommendations:
- Functions must be mention on the home page of the website
- Functions must be part of the Tutorials
- Developer (i.e. someone that writes application code, and does not necessarily know what Kubernetes is) persona is the main target for Functions
- A Developer using the website should be able to find a simple tutorial to get started with Knative to understand how to use it to build an application.
- A Developer using Functions in the tutorials should be able to use both Serving and Eventing.
- The current tutorials provide value, which should not be lost.
- Serving the tutorials covers a hello world service using a predefined image (no need to build or have docker), updating the service, and rolling out a new version of the service with percentage base traffic shifting.
- For eventing, the tutorials cover using a simple trigger to handle an event.
- Currently useful to devops/admin persona (i.e. knows about Kubernetes yaml), the tutorial shows the CLI but also shows the yaml behind it.
- It is ok to come up with a new set of tutorials but let's not lose some of the current value.
- It is up to the Docs WG to design and document how to best write a series of tutorials to cover the Knative features and now include Functions.
@csantanapr you asked for me with my SC hat on to summarize my position. I completely agree with your comments above and don't really have anything to add other than that I would be willing to take some of the writing/example work myself if Docs WG provides guidance.
For further context, this was discussed also in SC meeting July 7th, and July 14th, and I agree with the goals here!
@lance I think it's safe to say the proposal itself has been reviewed and approved now. Would you consider maybe closing this issue and raising specific doc issues for what needs to be documented in the site based off the proposal so that there's something actionable?
@lance I just remembered also that you were planning to move the proposal to the proper template, so maybe it's not approved yet. Any ETA for when that's expected? I think if it's decided to go another route in the meantime due to time pressures the proposal would need to change to reflect that.
@abrennan89 I was asking about this in Slack the other day.
I started to move the document about using Functions for the tutorial over to a Knative Feature Proposal doc today. But as I was doing so, I started to wonder if that’s perhaps a lot to bite off for the docs WG considering there are not a lot of active contributors currently. WDYT about starting more simply with a new heading on the main tutorial page “Using Knative Functions”.
Do you think something like this requires a full FT proposal?
@lance I really don't know to be honest; I don't have bandwidth atm to get into the details of what was in the original proposal, so I'm not sure how different this is to that. If the direction is changing entirely, I'd say it should be tracked in an FT, yes, to make it clear what was changed, what was the reasoning, who made the decision, etc. We should maintain transparency for major project changes like this IMO.
My biggest concern with this layout would be dropping the new topic (functions) into the middle of the existing tutorial, because I'm not sure it really fits there without messing up the flow. Probably better to discuss with Samia since she'll still be around when I am out on leave. I'm happy to defer to whatever she thinks is the right thing to do for now.
I still think we need to revisit the whole way our tutorials exist atm FWIW - they're not really proper tutorials, it seems to just be turning into a dumping ground for things that should probably have their own sections in the docs, e.g. there's no functions sections besides what you're proposing here, and I think that should maybe be added in its own right rather than just existing as part of the tutorial.
Last thing - I'd say if you do take this route, functions should be after serving and eventing, since you need those installed to deploy functions as services or connect functions to eventing components.
Last thing - I'd say if you do take this route, functions should be after serving and eventing, since you need those installed to deploy functions as services or connect functions to eventing components.
The Serving and Eventing sections of the tutorial don't cover installation. That's in the section just before "Using Knative Functions" in my example. My opinion is that the simplest and easiest way to digest Knative is through Functions, and presenting them first is the way to go.