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 introductory tutorial #254

Closed
Roel opened this issue Apr 18, 2020 · 3 comments · Fixed by #283
Closed

Add introductory tutorial #254

Roel opened this issue Apr 18, 2020 · 3 comments · Fixed by #283
Assignees
Labels
docs Documentation
Milestone

Comments

@Roel
Copy link
Member

Roel commented Apr 18, 2020

From the pyOpenSci review:

The documentation is very thorough, but I think one thing that would help new users is an "intro to working with pydov" tutorial. This tutorial would explains things at a level between the quickstart and the very detailed tutorials for each individual search object. What this tutorial would provide, that the current tutorials do not have, is an introduction to the core abstractions provided by the package. I notice that each DOV search tutorial follows the same structure, but there is not a lot of language about why a potential user might want to use some of the functionality, e.g. why get all the groundwater screens / boring holes within a bounding box.

The intro tutorial would ideally be a specific example of an analysis--it could even be one of the existing search tutorials--that introduces the concepts that repeat throughout the individual tutorials for each search object. This intro should be targeted at a "naive" researcher who is interested in having access to the data, but might not be familiar with some of the existing data structures and libraries that pydov leverages, e.g. the WFS protocol. I admit to a total lack of domain expertise in this area, so the devs' idea of what a "naive" researcher would know compared to mine might vary, but I think that adding an intro with more language about about what and why the package does what it does, in addition to how to do those things, would make it more welcoming to new users.

The documentation looks very detailed and instructive about how to use the library. I agree with David, maybe would be good to have a tutorial with an introduction something like a blog post (also it could be posted on PyOpenSci blog section).

@Roel Roel added the docs Documentation label Apr 18, 2020
@Roel Roel added this to the v2.0.0 milestone Apr 18, 2020
@pjhaest pjhaest self-assigned this Apr 28, 2020
@Roel
Copy link
Member Author

Roel commented Jun 3, 2020

@pjhaest Did you make any progress on this yet? This was one of the main points in the pyOpenSci review so I think we need to tackle this before proceeding with the review process. Be sure to push your WIP so we can collaborate here :)

@pjhaest
Copy link
Collaborator

pjhaest commented Jun 15, 2020

yes, sorry, last-minute project proposal came in between, along with some other things, as always.
I will start on it right away, if you haven't already? I was planning to add the tutorial as a seperate page to the docs, or would you prefer a seperate notebook?
Now that I look at it, actually that would be elaborating the 'Quick start' page, ok?

@pjhaest
Copy link
Collaborator

pjhaest commented Jun 22, 2020

short update, I just started a new Notebook. Will upload tomorrow. Easier to comment/change than an rst. And probably even better to leave it at that and refer to the notebook in the docs.

@pjhaest pjhaest linked a pull request Jun 25, 2020 that will close this issue
5 tasks
@Roel Roel closed this as completed in #283 Jul 16, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants