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

Restructure intro, getting started and tutorial #702

Merged
merged 34 commits into from Jan 16, 2024
Merged

Conversation

burnash
Copy link
Collaborator

@burnash burnash commented Oct 19, 2023

Description

This PR:

  • Adds more dlt topics coverage to the tutorial.
  • Restructures "Getting started" and "Introduction" pages.

@netlify
Copy link

netlify bot commented Oct 19, 2023

Deploy Preview for dlt-hub-docs ready!

Name Link
🔨 Latest commit 9cd4131
🔍 Latest deploy log https://app.netlify.com/sites/dlt-hub-docs/deploys/65a6a08551242d0008f27899
😎 Deploy Preview https://deploy-preview-702--dlt-hub-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@burnash burnash marked this pull request as draft October 19, 2023 08:04
@burnash burnash marked this pull request as ready for review October 26, 2023 07:00
@burnash burnash force-pushed the enh/docs_tutorial branch 2 times, most recently from c48c46b to 04713a5 Compare November 2, 2023 09:32
Copy link
Contributor

@AstrakhantsevaAA AstrakhantsevaAA left a comment

Choose a reason for hiding this comment

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

wow huge work!

imo:

  • Now I don’t really see the differences between the tutorial and how-to guides. if we combine them, nothing will change.
  • The Getting Started page has also lost its relevance. they are now similar to the Introduction page. maybe makes sense to merge them too?

update: at least the title Load data with API do not reflect the content. I got the idea of the tutorial section: it is something between How-to and using-dlt. mb rename it to "Load data with append, replace, merge mode"

@burnash
Copy link
Collaborator Author

burnash commented Nov 6, 2023

@AstrakhantsevaAA thanks for the comment!

Now I don’t really see the differences between the tutorial and how-to guides. if we combine them, nothing will change.

There should be a difference in the level of specificity: tutorial is a more general guide that teaches the core concepts, where how-to guides are more specific steps of instructions.

The Getting Started page has also lost its relevance. they are now similar to the Introduction page. maybe makes sense to merge them too?

  • I don't think Getting Started lost its relevance: I shortened the page so it's really a quick start: Install – Load - View.
  • Introduction is an overview of dlt: what that is + a brief showcase of different sources

@burnash
Copy link
Collaborator Author

burnash commented Nov 6, 2023

update: at least the title Load data with API do not reflect the content. I got the idea of the tutorial section: it is something between How-to and using-dlt. mb rename it to "Load data with append, replace, merge mode"

I believe an uninitiated user won't know what is append, replace and merge: the point of the first part is to teach them what that actually is and why they may need to use different loading modes.
I'm open to suggestion of a better naming for the section. My goal is to summarize the content of the first part.

Copy link
Collaborator

@rudolfix rudolfix left a comment

Choose a reason for hiding this comment

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

  1. PDF to weaviate is not visible in the index in the walkthrough
  2. I'd move it to examples. it looks way more like example to me. and we have too many walkthroughs
  3. the test for the above does not pass
  4. we have two files deploy_to_github_actions and dispatch-to-multiple-tables in the top level dir. (docs/website/docs) looks like a mistake

regarding content. tutorial is cool!
IMO removing the tabs with various examples from getting started is not a good idea. it showcases what you can do with dlt in a few lines of code and I was using it a lot when talking to users on slack to show how you can deal with pandas, csv or databases quickly. so practically I need that content somewhere at the top.

Copy link
Contributor

@AstrakhantsevaAA AstrakhantsevaAA left a comment

Choose a reason for hiding this comment

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

In recent days, I have often heard positive feedback from users about Getting Started page, I quote, “it’s convenient that by going through one page you can generally understand how the tool works.” It was good that it briefly showed how the tool works, without going into too much detail.
The tutorial is needed for a deeper understanding of these principles

@burnash
Copy link
Collaborator Author

burnash commented Nov 10, 2023

@AstrakhantsevaAA thanks for the feedback. The content from the getting started is still in the docs, I've moved it to the first part of the tutorial. My hypothesis is that it would not affect the understanding of the material. Another is that having a cohesive storyline also aids people in grasping dlt's key concepts fast.

@burnash burnash merged commit 77b070d into devel Jan 16, 2024
38 checks passed
@rudolfix rudolfix deleted the enh/docs_tutorial branch February 26, 2024 18:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants