Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "FAQ" to the knative.dev website #4668

Closed
Tracked by #4779
csantanapr opened this issue Jan 25, 2022 · 11 comments
Closed
Tracked by #4779

Add "FAQ" to the knative.dev website #4668

csantanapr opened this issue Jan 25, 2022 · 11 comments
Labels
triage/needs-docs-triage Issues to triage in the working group meeting

Comments

@csantanapr
Copy link
Member

csantanapr commented Jan 25, 2022

We want to add a FAQ page to help users.

Here is the initial set provided by the contractor Lionsway we worked with.

Frequently Asked Questions (FAQ)

What is Knative?

Knative is a system that works on top of Kubernetes. It helps development teams manage, monitor, and operate Kubernetes in a way that requires less technical knowledge and time. Knative is open-source, finding support and growth through a combination of individual contributors and industry-leading companies.

What's the difference between Knative Serving and Knative Eventing?

Knative has two main elements named Knative Serving and Knative Eventing. While they manage different tasks and outcomes and can operate independently, together, they help make Knative a powerful tool for dev teams and IT professionals.

  • Knative Serving runs serverless containers on Kubernetes with ease. Knative takes care of the details of networking, autoscaling (even to zero), and revision tracking. You have to focus on your core logic.
  • Knative Eventing allows for universal subscription, delivery, and management of events. Teams can build modern apps by attaching compute to a data stream with declarative event connectivity and a developer-friendly object model.

Where do I find documentation?

There are two forms of documentation for Knative. First, for end-user and high-level information, you can explore this website. For more granular information, you can see the documents for Knative's three main repositories, serving, eventing, and client.

How do I find help?

As an open-source project, you can find help by exploring the Knative documentation or reaching out to our community through GitHub, using the tag 'knative' on stackoverflow, and in the community Slack community using channels serving-questions and eventing-questions. The community is very active, and most questions are answered quickly.

How do I meet the Knative Community?

The community is very active on GitHub. There is also an active Knative Slack community where people swap ideas, talk about improvement, and get help.

How do I contribute to Knative?

Follow the knative contributor guide to get started. You can contribute in many forms like discussions, testing, reporting bugs, code changes, and documentation.

Do I need to use Istio?

You do not need to use Istio. Knative works with a variety of networking layers. You can find directions here.

@csantanapr csantanapr added kind/good-first-issue Denotes an issue ready for a new contributor. priority/high labels Jan 25, 2022
@csantanapr
Copy link
Member Author

Please comment with questions and answers you want to see on the website, once we have enough of them we can create a PR

@pmbanugo
Copy link
Member

  • Is there a managed cloud version of Knative?
  • Who are the contributors or companies backing the project?
  • What foundation is it under (CNCF, LF, etc)?

@csantanapr
Copy link
Member Author

Good ones @pmbanugo

@xtreme-sameer-vohra
Copy link
Contributor

  • Who is using Knative ? -> Link to Adopters

@csantanapr
Copy link
Member Author

/assign
I will work on this

@pmbanugo
Copy link
Member

pmbanugo commented Feb 3, 2022

Another question to add.

  • Does Knative support serverless functions?

@github-actions
Copy link

github-actions bot commented May 5, 2022

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Reopen the issue with /reopen. Mark the issue as
fresh by adding the comment /remove-lifecycle stale.

@github-actions github-actions bot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label May 5, 2022
@abrennan89
Copy link
Contributor

What was the reasoning for adding an FAQ rather than just improving the docs to be more useful?

I feel as if FAQs are a cheap way of avoiding deeper docs issues and there's no real good way to decide on what's in or outside of scope. Adding things indefinitely to an FAQ IMO doesn't make it more useful, it will just become another cluttered page where it's hard to find the info you're actually looking for. How would a user even know to look in the FAQ to begin with for this info?

I think the bot is right, mark this stale and let it die 🤷🏻

@github-actions github-actions bot removed the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label May 26, 2022
@csantanapr
Copy link
Member Author

FAQ that many websites have, and it seems useful, and many users share the same questions when they are new to the project/technology

The FAQ should not be a replacement for proper docs, and FAQ can point to specific sections of the docs for a complete answer.

@abrennan89
Copy link
Contributor

@csantanapr this article explains my perspective on it as a tech writer https://idratherbewriting.com/2017/06/23/why-tech-writers-hate-faqs/

@abrennan89 abrennan89 added triage/needs-docs-triage Issues to triage in the working group meeting and removed kind/good-first-issue Denotes an issue ready for a new contributor. priority/high labels Jun 22, 2022
@abrennan89
Copy link
Contributor

We discussed this in the Docs WG call today. Jist as follows:

  • Instead of providing an FAQ, which is sort of a jumble of information, all of the suggestions in this issue should have their own clear place in docs where they will be findable for people who are looking for them
  • There's already an issue for an About Knative page (Add an "About Knative" page #4791) which can answer questions about what's supported, components, what foundation is Knative under, etc. per the comments here.
  • We will open an additional issue to create a page named something like Adopters (? name needs more discussion probably) that provides info about who is using Knative, case studies, things like managed cloud offerings (since these are not a community thing but might be provided by partners / companies using Knative in products or on their platforms)
  • We should open a separate Epic / issue re Istio vs Kourier vs other options, what is required, what isn't, and why users would use one over the other - this should be addressed adequately in the core docs so that it's not a question that's being asked all the time
  • All the other "FAQs" in the description of this issue should be obvious from the Knative site as is, and if they're not, it's a bigger issue about our content strategy that will not be solved by adding an FAQ page

I am closing this issue and will be opening an Epic that includes the new issues discussed here, as well as some other topics we talked about on the call today. cc @snneji in case there's anything you'd like to add.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
triage/needs-docs-triage Issues to triage in the working group meeting
Projects
None yet
Development

No branches or pull requests

4 participants