question: one page or many?

gvwilson / sql-tutorial

The Querynomicon: An Introduction to SQL for Wary Data Scientists

https://gvwilson.github.io/sql-tutorial/

Other

447 stars 47 forks source link

question: one page or many? #49

Closed gvwilson closed 5 months ago

gvwilson commented 5 months ago

The first version of this tutorial had all of the material on one long page.
- Except for the material on Python and PostgreSQL, which was on separates pages.
This version divides the main material between 12 pages.
- Pro: topic structure is easier to see
- Con: 3 of the 9 pages (SQL Tools, More Tools, and Odds and Ends) are miscellaneous topics thrown together
Please add a comment below to tell me whether you prefer one long page or multiple pages.

yabellini commented 5 months ago

I prefer one long page because I can search for what I'm looking for in one place.

simonw commented 5 months ago

Is "both" a useful suggestion?

A single page is easier to dump into a tool like Pocket for offline reading, but multiple pages are more useful for things like landing on the right piece of information from a Google search.

So how about defaulting to multiple pages but providing an automatically compiled (and search engine excluded, to avoid duplicate content penalties) single page version for people who want to grab an offline or single-searchable version?

hcooney commented 5 months ago

Many pages makes it easy for someone with some knowledge to orient themselves and skip introductory material.

aflip commented 5 months ago

Multiple pages, but with a persistent table of contents. eg Biostats for biomedical research So it is easy to 1. search the whole book/resource from one page 2. Skip and travel easily to the pages that one needs at that moment 3. review is easier because I can pick what I want to review and just go to that page. A smiliar structure is also seen in SQL Bolt, which is what I ( a medical scientist) used to learn SQL

defuneste commented 5 months ago

I prefer the new version with multiples pages and less scrolling down.

I would also use an offline single page version. I assume for that I can also fork/clone the repo and build it for that specific need so in my mind it take lower "priority" that "good web version".

gvwilson commented 5 months ago

thank you all for your feedback - I've consolidated the lesson into three pages (core, tools, and advanced) which I hope you'll find a good balance. @simonw I'll see if there's an easy way to get both multi-page and single-page versions out of the same source without hacking Ark too much - thank you for the suggestion.