Move FAQs from documentation onto website

[stichbury]

We've discussed previously that we want to move most of the FAQs from the documentation onto the website. This is motivated partly because the docs are unwieldy and we need to make FAQs (which are popular) more visible, and also because I don't think they fit in the docs as they are (they're higher level and could be rewritten to have a better marketing slant.

So this ticket is to initiate the discussion/process of creating a new FAQ page. Separately, I will pick up content revision over on the docs to prepare the copy and then you'll have a better idea for what is coming in terms of page design.

[tynandebold]

Have we made a determination of what questions we'll move to kedro.org. Will it be everything from that FAQ page, or a subset, or some questions from there and then some that aren't currently present?

Separately, we should think about redirecting users from the current FAQ page to the newly-built one once it's published so we don't lose that traffic.

Lastly, we'll need to update our TSC documentation to point to the new place where we keep a list of maintainers. This is also the place we ask people to add themselves to the list that we then vote on.

[tynandebold]

@stichbury / @yetudada to add an example FAQ here.

[astrojuanlu]

I'm a bit late to the party but I'm wondering if it would be better to have a Kedro FAQ on the website for more high level questions, like What is Kedro?, What are the primary advantages of Kedro?, How does Kedro compare to other projects?, but then leave the more technical content in the docs.

This might have the effect of yielding 2 FAQ pages though, which might be less than ideal.

Alternatively, given that one of the reasons (or even the main reason) is that the docs are a bit disorganized, I'm wondering if we should prioritize organizing the docs instead. The reason I say this is because I don't see us moving back a page from the website to the docs whenever we consider they're in better shape.

[stichbury]

You're absolutely right, @astrojuanlu that is exactly what we plan to do.

I want to organize the docs to remove the high level (marketing-ish) content and move it to the website.

The technical FAQ will stay in the docs, although there aren't many. I have a philosophy about FAQ but won't repeat it here (I'll find the ticket where it is included: kedro-org/kedro#1985 and kedro-org/kedro#2026

[stichbury]

Here's a typical FAQ that will go onto the website. It needs to be re-written but this is the kind of level of the content that should not be in the docs but is valuable as part of our web presence:

If you're a Data Scientist, then you should be interested in Kedro because it enables you to:

• Write cleaner code, so that your Python code is easy to maintain and re-run in future; it does this by applying standardisation and software-engineering best practices
• Make a seamless transition from development to production, as you can write quick, throw-away exploratory code and
  transition to maintainable, easy-to-share, code experiments quickly
• Stay current in machine learning operations (MLOps), as Kedro takes care
  of the principles you need to create data science code that lasts; you'll always be two steps in front of industry standards
• Integrate with your data science workflow, and use tools in the data science ecosystem, like Tensorflow, SciKit-Learn or Jupyter notebooks for experimentation. You can also take advantage of tools to produce for producing
  quality code like Sphinx (documentation); black, isort and flake8 (code linting and formatting); and,pytest (unit tests)

If you're a Machine-Learning Engineer or Data Engineer, then you should be interested in Kedro because:

• Standardisation creates efficiency, establishing proper analytics code foundations can save up to 80% of your hours down the road when putting models in production
• You can focus on solving problems, not setting up projects, Kedro provides the scaffolding to build more
  complex data and machine-learning pipelines. There's a focus on spending less time on the tedious "plumbing" required to maintain analytics code; this means that you have more time to solve new problems
• A data-driven framework makes pipelines easy, by permitting data versioning, incremental computing and automatic pipeline running order resolution
• It is platform-agnostic, allowing you to choose what compute or platform to run your Kedro workflow; Databricks
  and products like Kubeflow, Argo, Prefect and Airflow are deployment targets
• It is easy to extend, by using Hooks to add in tools like MLFlow (experiment tracking), Great Expectations (data validation and profiling) and Grafana (pipeline monitoring)

If you're a Project Lead, then you should be interested in Kedro because:

• It allows for effortless teamwork and an ability to scale analytics across an organisation. Kedro standardises team workflows; the modular structure of Kedro facilitates a higher level of collaboration when teams solve problems together
• We stand for no more fire drills. You can remove long delays created because you have to refactor a data
  science proof of concept into production
• You don't need to start from scratch, standardisation and separation of concerns makes it possible to reuse analytics code
• See your project like never before, Kedro’s pipeline visualization plugin lets you see a blueprint of your team's developing workflows and better collaborate with business stakeholders

[stichbury]

I've just been scouting around for examples of Q&As.

• There's this on Medium: I quite like the look
  https://medium.com/creator-tools?source=customize_suggestions_entities_to_follow_sidebar------------------------------------- (I know, weird URL -- at the bottom of the page it's the "More about publishing on Medium:| section) but the extra click to open/close isn't that accessible

• I quite like the Confluent Cloud design where if you click on a question it just jumps you to an anchor https://www.confluent.io/confluent-cloud-faqs/

If we expected to have loads of FAQs, we may want to design a landing page and a page design for a Q&A pair with breadcrumbs back to the main FAQ, but TBH I don't see that happening.

The content on the Kedro FAQ page is deliberately NOT a knowledge base of loads of technical Q&As. It's high-level marketing stuff about Kedro. Mostly taken from https://kedro.readthedocs.io/en/stable/faq/faq.html (with some re-writing). I don't expect there to be code snippets. As long as we can include graphics and rich text, I don't expect it to be as demanding as a typical blog page.

[Mackay031]

Hey team, this is what I am thinking for FAQ's

Initial view:

Expanded view:

Lets have a chat further....

[tynandebold]

@stichbury we discussed in standup that if you have any feedback for the designs @Mackay031 posted above you can add it here :)

[stichbury]

That's really nice! Thanks @Mackay031 I really like it, particularly the arrows, as that was what I liked on the Medium example.

I'm wondering if they need to be just in one column on the right hand side though. Could they not be across the whole screen since there's very little text to put on the left (and neither of those sentences is particularly essential, we have them elsewhere).

[Mackay031]

Hi Jo, thanks for the feedback. I started out with just one column, but as a general rule of thumb, I prefer not to have more than 10 (15 at most) words per line. It becomes harder to read sentences with more words, with eyes having to move long distances. That is why I settled with a 2 column grid. We could also possibly have a sticky left hand column, so it follows the scroll, allowing users to have the options to go to Slack etc. It also fills the negative space.

[stichbury]

Thanks @Mackay031 that makes sense. I see what you mean about sentences spread across the whole span. Happy to go with your design and maybe have that sticky in the LH column to fill the space. Sounds good to me.

[tynandebold]

@stichbury where can we find the content for this page?

[tynandebold]

Synopsis from today's Design Demo meeting:

• FAQ section will go on homepage (not a separate page), after the features section and before case studies
• We'll add an anchor link to the nav, between Features and Get Started