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

[Ready] Remove FAQ documentation content, fix links #2373

Merged
merged 17 commits into from
Mar 20, 2023
Merged

Conversation

stichbury
Copy link
Contributor

@stichbury stichbury commented Feb 28, 2023

NOTE TO REVIEWERS. You can see the built docs here.

Description

Part of #1985, and the milestone to improve the onboarding experience, paying particular attention to FAQs.

The overall plan is to:

Move marketing FAQs to the website

See this website issue for ongoing work.

Note The copy that will go onto the site is available for review in Box but is also dependent on our pending messaging discussion.

Add more technical FAQ content in the documentation where it's relevant

We now have a spaceflights FAQ, as one example. As we improve docs we will favour content that is structured to answer typical user questions (in part because SEO).

Why remove a popular page?

My thoughts on the fact that the FAQ page is currently a popular one in the docs are that people are looking for information, used to checking FAQs, so they visit the page.

They're not there to read the page end-to-end and -- I would guess -- they're not really getting much out of the existing content, which is a mixture of marketing copy, a list of names and a few technical details that didn't fit elsewhere.

Some people will also end up on the FAQ through organic search and we need to make sure that the copy (in Box, see note above) is optimised so they get to the Kedro website and find what they need.

I want to prioritise content in the coming weeks that fills any gaps left by the FAQ. So, aside from the website copy, we also need to do the following:

  • Write a "Commonly asked questions about Kedro blog post (which may be this one)
  • Create a revised blog post from Joel's data layers TDS post
  • Make a new 'skinny' FAQ page in the docs that asks common technical questions, but doesn't answer them, it just pushes readers through to the relevant content (this page would use the Heap analytics data as a guide to determine where most popular pages are, and thus what likely questions we should answer -- we also have a collection from Joel and can review Slack for more)

Development notes

  • Removed FAQ content and graphics that are no longer needed
  • Moved the list of "Humans behind Kedro" to the root Kedro README
  • Also removed the other two pages in the FAQ section
  • Fixed links where they pointed to removed content and updated the exclusions list in conf.py because the linkcheck doesn't understand anchors and I'm pointing to an anchor in Kedro's README

Checklist

  • Read the contributing guidelines
  • Opened this PR as a 'Draft Pull Request' if it is work-in-progress
  • Updated the documentation to reflect the code changes
  • Added a description of this change in the RELEASE.md file
  • Added tests to cover my changes

Signed-off-by: Jo Stichbury <jo_stichbury@mckinsey.com>
@astrojuanlu astrojuanlu self-requested a review February 28, 2023 11:43
@stichbury stichbury changed the title Remove FAQ documentation content, fix links [Draft] Remove FAQ documentation content, fix links Feb 28, 2023
Signed-off-by: Jo Stichbury <jo_stichbury@mckinsey.com>
@stichbury stichbury marked this pull request as ready for review February 28, 2023 15:44
@stichbury stichbury requested a review from yetudada as a code owner February 28, 2023 15:44
@stichbury stichbury changed the title [Draft] Remove FAQ documentation content, fix links Remove FAQ documentation content, fix links Feb 28, 2023
Copy link
Member

@astrojuanlu astrojuanlu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot @stichbury! Left a few comments

docs/source/development/commands_reference.md Show resolved Hide resolved
docs/source/get_started/install.md Outdated Show resolved Hide resolved
docs/source/get_started/install.md Outdated Show resolved Hide resolved
docs/source/get_started/install.md Outdated Show resolved Hide resolved
docs/source/get_started/install.md Outdated Show resolved Hide resolved
docs/source/kedro_project_setup/settings.md Show resolved Hide resolved
docs/source/resources/glossary.md Outdated Show resolved Hide resolved
docs/source/resources/glossary.md Outdated Show resolved Hide resolved
docs/source/tutorial/set_up_data.md Outdated Show resolved Hide resolved
Copy link
Member

@astrojuanlu astrojuanlu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the addition of gh-2377 this PR looks good to me!

@stichbury
Copy link
Contributor Author

I am not going to merge this PR until we have the following in place:

* Agreement on general messaging

  • Updated copy for "marketing" FAQs (these are in Box)
  • Transitioned those FAQs from their location in Box onto website
  • Added a set of basic technical FAQs to the FAQ page in the docs

@stichbury stichbury changed the title Remove FAQ documentation content, fix links [Do not merge] Remove FAQ documentation content, fix links Mar 6, 2023
@stichbury stichbury self-assigned this Mar 6, 2023
@stichbury stichbury added the Component: Documentation 📄 Issue/PR for markdown and API documentation label Mar 6, 2023
@stichbury stichbury marked this pull request as draft March 6, 2023 10:52
Signed-off-by: Jo Stichbury <jo_stichbury@mckinsey.com>
Signed-off-by: Jo Stichbury <jo_stichbury@mckinsey.com>
Signed-off-by: Jo Stichbury <jo_stichbury@mckinsey.com>
Signed-off-by: Jo Stichbury <jo_stichbury@mckinsey.com>
@stichbury stichbury changed the title [Do not merge] Remove FAQ documentation content, fix links [Ready] Remove FAQ documentation content, fix links Mar 15, 2023
@stichbury stichbury marked this pull request as ready for review March 15, 2023 13:44
Copy link
Member

@merelcht merelcht left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks really good! ⭐ I left one minor comment.

docs/source/tutorial/tutorial_template.md Outdated Show resolved Hide resolved
Signed-off-by: Jo Stichbury <jo_stichbury@mckinsey.com>
@stichbury stichbury merged commit a10485f into main Mar 20, 2023
@stichbury stichbury deleted the 1985-remove-faqs branch March 20, 2023 11:38
dannyrfar pushed a commit to dannyrfar/kedro that referenced this pull request Mar 22, 2023
Fina; push to remove FAQs that are about Kedro and put them on the website, focussing FAQs instead on technical topics (though more are still needed).

Signed-off-by: Danny Farah <danny.farah@quantumblack.com>
jmholzer pushed a commit that referenced this pull request Mar 29, 2023
Fina; push to remove FAQs that are about Kedro and put them on the website, focussing FAQs instead on technical topics (though more are still needed).

Signed-off-by: Jannic Holzer <jannic.holzer@quantumblack.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Component: Documentation 📄 Issue/PR for markdown and API documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants