the sqlite3 documentation would be pretty good if it wasn't tragic...

classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|

the sqlite3 documentation would be pretty good if it wasn't tragic...

Ben Earhart
...that the person(s) that has no problem writing small, but solid, walls
of technical detail and drawing intricate circularly recursive syntax
diagrams which require multiple levels of detail to coherently represent,
can't be bothered to write example sql code for the top dozen things that
most surely cover better than the majority of real-world uses cases.

Does anybody here know where such a thing might exist? I think sqlite3 is a
gem but, for whatever reason, I have had poor luck getting sqlite3 sql code
examples - just scraps here and there. I don't use it near as much as I
could simply because of difficulty getting examples for a few basic schema
patterns.

Thanks,
Ben
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if it wasn't tragic...

Shawn Wagner
The syntax diagrams are created by a tcl script, not drawn by hand:
https://wiki.tcl-lang.org/page/Generating+Syntax+Diagrams+Using+Tk

I think a lot of the documentation assumes the reader already knows the
basics of sql... What kind of examples are you thinking of?


On Tue, Jun 25, 2019, 8:16 PM Ben Earhart <[hidden email]> wrote:

> ...that the person(s) that has no problem writing small, but solid, walls
> of technical detail and drawing intricate circularly recursive syntax
> diagrams which require multiple levels of detail to coherently represent,
> can't be bothered to write example sql code for the top dozen things that
> most surely cover better than the majority of real-world uses cases.
>
> Does anybody here know where such a thing might exist? I think sqlite3 is a
> gem but, for whatever reason, I have had poor luck getting sqlite3 sql code
> examples - just scraps here and there. I don't use it near as much as I
> could simply because of difficulty getting examples for a few basic schema
> patterns.
>
> Thanks,
> Ben
> _______________________________________________
> sqlite-users mailing list
> [hidden email]
> http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
>
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if it wasn't tragic...

R Smith-2
In reply to this post by Ben Earhart
On 2019/06/23 8:14 AM, Ben Earhart wrote:
> ...that the person(s) that has no problem writing small, but solid, walls
> of technical detail and drawing intricate circularly recursive syntax
> diagrams which require multiple levels of detail to coherently represent,
> can't be bothered to write example sql code for the top dozen things that
> most surely cover better than the majority of real-world uses cases.


As Shawn pointed out, diagrams are scripted, but more importantly - 3
things to consider:

A - SQLite is not SQL. SQLite provides an Engine to deal with SQL, but
SQL is a thing unto itself and there are countless training, educational
and example content on the net (see below for examples). SQLite often
changes/updates to better follow the SQL standard, or rather, newer SQL
technology. It would both be presumptuous and unsafe for SQLite to
trespass on the education of SQL itself. (Even maintaining that would be
a job for many).  A calculator manufacturer can show you how to enter a
math function, but it's not in the business of teaching you how to do
math, not because they don't want to, just because it isn't their
authority and they shouldn't trespass on the domain of educational
institutions.

B - The premise that "...most surely cover the majority of real-world
use cases..." is just not true. SQL use cases and Query statements are
literally infinite. For every query that was ever written on Earth,
ten-fold more will be written in the near future, and infinitely more
before the Sun explodes. What's the top 1% of infinity?  For SQLite to
give examples of real-world use cases (as opposed to merely
demonstrating internal specific methodology) would be like a car
manufacturer (say Ford) suggesting driving routes to your nearest shop.
There are many viable routes, it is not their domain and they would by
no means be a better authority on it than a map book or google maps, or
indeed your own knowledge of your area.

C - There are expert advisors who do this already, for whom it is their
main function and they have supportive communities and the like. On this
very forum, you can ask any SQL question and I promise someone will come
up with great SQL to achieve just that. In fact, likely 5 someones will
come up with different ways of achieving it in SQL.  <opinion>The
premise that SQL examples are hard to find seems perhaps more a result
of  google's algorithm becoming an advertising monstrosity rather than a
good search engine. </opinion>


> Does anybody here know where such a thing might exist? I think sqlite3 is a
> gem but, for whatever reason, I have had poor luck getting sqlite3 sql code
> examples - just scraps here and there. I don't use it near as much as I
> could simply because of difficulty getting examples for a few basic schema
> patterns.

May I suggest one of my favourites: W3-Schools
(https://www.w3schools.com/sql/default.asp) which has excellent basic
tutorials on getting things done (more than just the dozen top real
world examples).

Another, which is more SQLIte-oriented if you prefer, is:
http://www.sqlitetutorial.net/

Also, from our own side, if you have a Windows machine or WINE
somewhere, you can try the free sqlitespeed (https://sqlitespeed.com/)
and during install tick the "Include example SQL" (I forget the exact
caption, but that's the gist of it) which includes a whole lot of
example scripts mostly gathered from this forum, but perhaps geared more
towards doing creative things with SQLite specifically rather than
general-purpose SQL such as W3-Schools would do.


>
> Thanks,
> Ben


Best of SQL luck mate!
Ryan


_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if it wasn't tragic...

Stephen Chrzanowski
In reply to this post by Ben Earhart
I've always been perturbed by the term "Real World Examples".  Because...
well.. Everything is different from one building to the next.  How I make
my SQL calls is going to be different than the company across the street.
Heck, even the guy sitting across from me will come up with a different way
to get to the same answer.

"Real world" examples are really hard to come by considering that there are
soo so many "real world" types of information that needs to be asked for.
There is no "standard" query to get the same answer.  How I pull data out
of SQLite (Or any SQL DBMS) is going to be different than how Dr Hipp, how
Ryan, how Simon, or how any other regular user posts on here.  There's
thousands, if not MILLIONS types of queries to get the exact same answer
for a very specific required answer.  For instance, there's nearly an
infinite number of ways to get the answer "42" out of a database, but a
"real world" example doesn't exist because it can be done way too many ways.

The best way to figure out SQL is to dive in, and ask lots of questions.
If it breaks, find out another way.  Post your query here, demonstrate what
you've done to try and solve the answer to why you're getting the wrong
answer, and explain what the answer should be.  Learning anything is a
process, and SQL is absolutely no exception to that rule.  Or law for that
matter.

I've asked a few questions here that probably didn't make sense to anyone
else in this forum, but were crystal clear in my head.  Google, Ask,
Metacrawler, Yahoo, and yes, even Bing, will get you a part of the way
there, but none of those search engines will provide you a link to a single
site that says "To get to that answer, you must go this route, there's no
other alternative". (Ok, other than for syntax differences, you HAVE to go
a route, but...)

**Note:
SQL has a "standard" but no one really follows it to the "T".  You'll find
different quirks between different engines and their languages.  So a
particular query may work on one engine or multiple engines, but, that same
query may not work on one.  Generally, though [ select 1+1; ] should return
2 on ALL SQL engines.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
ajm
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

ajm
Irreproachable argumentation, which in my humble opinion is little or nothing useful to those who want to enter in the diabolic world of SQL. Especially, if you have not yet managed to change the chip and find out that for example, you must carry out a program without using variables.

All the programming gurus I've read, agree that the best way to master a language (SQL is) is to read code from good programmers and I do not remember anyone who says that you ask in the forums when you have any questions, and the sad reality is that it is difficult to find examples of SQL, apart from being attentive to these pages where sometimes you learn a lot in the code of some answers.

I understand and empathize absolutely with the O.P. and must add that in the documentation of SQLite, I have always missed examples and comments that, for example, can be found in the PHP doc.

Just a thougth.

--
A. J. Millan.

>
> ---- Mensaje original ----
> De: Stephen Chrzanowski <[hidden email]>
> Para:  SQLite mailing list <[hidden email]>
> Fecha:  Wed, 26 Jun 2019 10:18:29 -0400
> Asunto:  Re: [sqlite] the sqlite3 documentation would be pretty good if itwasn't tragic...
>
> I've always been perturbed by the term "Real World Examples".  Because...
well.. Everything is different from one building to the next.  How I make
my SQL calls is going to be different than the company across the street.
Heck, even the guy sitting across from me will come up with a different way
to get to the same answer.

"Real world" examples are really hard to come by considering that there are
soo so many "real world" types of information that needs to be asked for.
There is no "standard" query to get the same answer.  How I pull data out
of SQLite (Or any SQL DBMS) is going to be different than how Dr Hipp, how
Ryan, how Simon, or how any other regular user posts on here.  There's
thousands, if not MILLIONS types of queries to get the exact same answer
for a very specific required answer.  For instance, there's nearly an
infinite number of ways to get the answer "42" out of a database, but a
"real world" example doesn't exist because it can be done way too many ways.

The best way to figure out SQL is to dive in, and ask lots of questions.
If it breaks, find out another way.  Post your query here, demonstrate what
you've done to try and solve the answer to why you're getting the wrong
answer, and explain what the answer should be.  Learning anything is a
process, and SQL is absolutely no exception to that rule.  Or law for that
matter.

I've asked a few questions here that probably didn't make sense to anyone
else in this forum, but were crystal clear in my head.  Google, Ask,
Metacrawler, Yahoo, and yes, even Bing, will get you a part of the way
there, but none of those search engines will provide you a link to a single
site that says "To get to that answer, you must go this route, there's no
other alternative". (Ok, other than for syntax differences, you HAVE to go
a route, but..)

**Note:
SQL has a "standard" but no one really follows it to the "T".  You'll find
different quirks between different engines and their languages.  So a
particular query may work on one engine or multiple engines, but, that same
query may not work on one.  Generally, though [ select 1+1; ] should return
2 on ALL SQL engines.


_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

Simon Slavin-3
On 26 Jun 2019, at 5:58pm, [hidden email] wrote:

> I understand and empathize absolutely with the O.P. and must add that in the documentation of SQLite, I have always missed examples and comments that, for example, can be found in the PHP doc.

Likewise.  The PHP system of documentation, where each page of the manual allows comments, gives users, rather than the dev team, the responsibility of making good code segments available.  It works very well for that piece of software.

I too have missed sample code from the SQLite documentation.  I agree that there are some drawbacks to including it.  But there are some things, like the correct sequence is for understanding ROLLBACKs, which are strange and complicated when explained in text but are far easier to understand when seen as sample code.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

Jens Alfke-2
In reply to this post by ajm


> On Jun 26, 2019, at 9:58 AM, [hidden email] wrote:
>
> the sad reality is that it is difficult to find examples of SQL, apart from being attentive to these pages where sometimes you learn a lot in the code of some answers.

I don’t know what to say to that! Have you looked outside the SQLite website? A simple web search like [sql examples] returns zillions of hits. There are innumerable books on SQL. And with all the open source software out there, if you just look up an application that does something like what you want to do (a CMS, say), you can browse its code for the SQL schema and queries it uses.

> I understand and empathize absolutely with the O.P. and must add that in the documentation of SQLite, I have always missed examples and comments that, for example, can be found in the PHP doc.

PHP is a language. SQLite is not. It stands to reason that the documentation for a language would provide lots of examples of its use; the documentation for a compiler/runtime, not so much. (For example, compare K&R with the GCC or Clang documentation.)

—Jens
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

Robert Hairgrove
In reply to this post by ajm
On 26.06.19 18:58, [hidden email] wrote:

> Irreproachable argumentation, which in my humble opinion is little or nothing useful to those who want to enter in the diabolic world of SQL. Especially, if you have not yet managed to change the chip and find out that for example, you must carry out a program without using variables.
>
> All the programming gurus I've read, agree that the best way to master a language (SQL is) is to read code from good programmers and I do not remember anyone who says that you ask in the forums when you have any questions, and the sad reality is that it is difficult to find examples of SQL, apart from being attentive to these pages where sometimes you learn a lot in the code of some answers.
>
> I understand and empathize absolutely with the O.P. and must add that in the documentation of SQLite, I have always missed examples and comments that, for example, can be found in the PHP doc.
>
> Just a thougth.
>
> --
> A. J. Millan.

After working for several years in the field (having worked with dBase,
MS-Access, Oracle, DB2 (including DB2 on IBM-AS/400) and MySQL database
applications BEFORE doing any work with SQLite), I find myself
constantly going back to two books which I consider the "Old" and the
"New" Testaments of the SQL bible, if there is such a thing:

Old: "An Introduction To Database Systems" by C. J. Date, ISBN
0-201-82458-2 (I have the 6th edition);
New: "SQL For Smarties: Advanced SQL Programming" by Joe Celko, ISBN
1-55860-576-2 (I have the 2nd edition).

Then there are the SQL ANSI/ISO standards documents themselves, but I
wouldn't look for many hands-on examples there. Of the two books I just
mentioned, Joe Celko's book has the most abundant real-world examples,
but the Date book also has lots of examples albeit on a more basic
level. Caveat: I have read that the latest edition(s) of Joe's book
unfortunately has many typo's, but you should be able to work around
those IMHO.

SQL is, IMHO, very much a "learning by doing" language. The vendor or
programmer of an SQL RDBMS implementation should not be expected to do
much in the way of tutorials except where their implementation might
deviate (or expand upon) the functionality required by the standards
they claim to implement.

HTH,
Bob Hairgrove

_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

Warren Young
In reply to this post by Simon Slavin-3
On Jun 26, 2019, at 11:11 AM, Simon Slavin <[hidden email]> wrote:
>
> I too have missed sample code from the SQLite documentation.  I agree that there are some drawbacks to including it.  But there are some things, like the correct sequence is for understanding ROLLBACKs, which are strange and complicated when explained in text but are far easier to understand when seen as sample code.

It would be nice to have one good example below each racetrack diagram.  This set of examples doesn’t have to be comprehensive; I agree with the other arguments on this point.  It’s just that it’s easier to read a racetrack diagram when you’ve got a worked example showing how all of the verbs and nouns get strung together into a working bit of SQL code.

It would also be nice to have examples in the SQLite docs wherever SQLite deviates significantly from the rest of the SQL world:

1. Joins.  If you aren’t careful to include “SQLite” in your web search terms, you’ll often get code that just won’t execute on SQLite, because most of the result pages are written by people running DBMSes that allow them to create a RIGHT OUTER UPSIDE DOWN INVERSE DOUBLE JOIN WITH EXTRA SPIN.

2. ALTER TABLE.  SQLite’s implementation of this is sufficiently low-featured that one often wants common workarounds.  You can find a dozen web sites that will give you a sensible workaround for SQLite’s lack of, say, DROP COLUMN, but it’d be nice to find it in the SQLite docs, too.

3. Lack of types.  Some DBMSes have a data type for every strange thing they’ve been asked for by the Fortune 500 over the past 4 decades, but not SQLite.  There should be a set of recipes to work around SQLite’s relatively small set of built-in types.  For instance, there’s no specific TIMESTAMP type, but you can construct one with an INTEGER and the built-in data/time functions.  That drags in pros-and-cons discussions of time_t vs Julian dates, etc.

There’s also the collapsing of types in SQLite, which is currently fairly well-documented, here:

    https://www.sqlite.org/datatype3.html#affinity_name_examples

For example, the fact that SQLite really doesn’t make any distinction between, say, VARCHAR(255) and TEXT.  What I want, then, is for that table to be more comprehensive, so that whatever weird data type you search for, you either get a simple mapping to one of SQLite’s few base data types or to a recipe showing how to construct a suitable alternative.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

Warren Young
On Jun 26, 2019, at 2:22 PM, Warren Young <[hidden email]> wrote:
>
> 3. …types…table…more comprehensive, so that whatever weird data type you search for, you either get a simple mapping to one of SQLite’s few base data types or to a recipe showing how to construct a suitable alternative.

…or a pointer to a SQLite extension to provide the feature.

For example, the current Affinity Name Examples table I linked in the prior post says that DECIMAL(10,5) maps to NUMERIC, but you have to read the rest of that page carefully to realize that it’s giving you a limit case, beyond which SQLite will lose precision.  It’s not clear just from that type table that DECIMAL(11,6) gives you no more precision than DECIMAL(10,5) in SQLite:

    sqlite> create table x (a DECIMAL(11,6));
    sqlite> insert into x values(123456789.123456789);
    sqlite> select * from x;
    123456789.123457

Note that it’s a silent clamp on the value.  There is no warning that you’ve done something silly, either on CREATE TABLE or on INSERT.

Ultimately, this is because SQLite uses platform IEEE 754 doubles and platform ints for storage, whereas big-boy DBMSes tend to use arbitrary-precision math libraries for DECIMAL.  

The place for that warning isn’t in SQLite itself, but instead in its docs, where it should make the limit more clear, then point those who need to get beyond that limit to this:

    https://chiselapp.com/user/lifepillar/repository/sqlite3decimal/index

Granted that that’s a third-party, not-for-production, function-only extension, not a true SQLite data type, but at least pointing it out will clue people into the fact that SQLite’s DECIMAL isn’t really doing anything for you other that you can’t already do with REAL or INT.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

ingo
In reply to this post by Warren Young


On 26-6-2019 22:22, Warren Young wrote:
> 3. Lack of types.

Not being a programmer, that was a revelation to me, I started with
Postgresql (upgrading to SQLite now) and wasted way to many hours on
deciding the type. In SQLite it is straight forward. If I use
CURRENT_TIMESTAMP in the shell it shows me some text so that's the type
I choose. If I need finer granularity I do it in the application, not in
the library unless there is a specific function for it.

Regarding the docs, they are dense and not always clear to me as a non
native speaker. Slowly I'm seeing a pattern though, start with the
diagrams and if the SQL does not work, find the exception why in the text.

Ingo
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

Warren Young
On Jun 26, 2019, at 2:58 PM, ingo <[hidden email]> wrote:
>
> On 26-6-2019 22:22, Warren Young wrote:
>> 3. Lack of types.
>
> Not being a programmer, that was a revelation to me

Behind my prior two posts isn’t an attitude of criticism of SQLite’s design and implementation, but rather an itch created by the gaps in its capabilities relative to popular big-boy RDBMSes.  Because SQLite isn’t the only SQL DBMS, there’s a lot of info on the web and in books about those other DBMSes, so there’s a lot of info that doesn’t properly apply to SQLite.

SQLite can fill those gaps in any of several ways:

1. Add features.  Problem: risks damage to its “lite” nature.

2. Let other authors paper over of those gaps.  Problem: they don’t always show up as high as sqlite.org in web search results, even when you include “SQLite” as a search term.

3. Add such docs in the official SQLite docs, so that for each topic where SQLite diverges from the rest of the SQL world, the correct answer is among the first few web search results.

sqlite.org has a lot of Google juice, which gives it a greater responsibility for being comprehensive than a lesser-ranked site.  To the extent that the SQLite docs fail to take up that responsibility, its Google juice will drain away as people link to arguably better sources.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if it wasn't tragic...

James K. Lowden
In reply to this post by Ben Earhart
On Sat, 22 Jun 2019 23:14:08 -0700
Ben Earhart <[hidden email]> wrote:

> can't be bothered to write example sql code

While I'm sure you're irritated, that criticism is misplaced.
You might want to take a step back. Tools that work with standardized
languages don't define the language they process.  You won't find many
examples included with your C compiler or ODBC driver, either.  

It's not a matter of can't be bothered.  It's a matter of
choosing.  

Anyone who's done a lot of writing, especially technical writing IMO,
has the problem of deciding what to include and what to exclude.
Anyone who reads documentation appreciates the difficulty of finding
the relevant information, and of skipping over what isn't relevant in
case it (surprisingly) is relevant.  

SQL examples in SQLite documentation, except where they illustrate some
preculiar aspect of SQLite's SQL, would be only so much noise: they
would hinder the job of understanding the grammar.  Necessarily, being
examples, they would highlight only certain features of the grammar.  

You may say examples would help the beginner.  But the reference manual
is not a tutorial and not a user guide and not an introduction to SQL.
The beginner is well advised to consult those kinds of materials as a
way to learn SQL, and come back to the SQLite manual to learn how to
use SQLite.  Specifically.  

I started learning SQL before Bill Gates discovered the Internet.
"Diving in" in those days meant going down to the bookstore at lunchtime
to find out what there was to find out.  Still today, the best way to
learn about something is to read about it from someone who wants to
explain it to you.  CJ Date has sold 800,000 copies of his textbook,
which in the technical book market is a runaway best seller.  There are
dozens of others just as good but not as popular.  

Avoid, if I may suggest, anything that promises to make SQL easy or
implies that it's hard.  It's not hard.  But it may well be the only
language you ever use that is grounded in math & logic.  It has a
more-than-casual relationship to the Relational Model, itself based on
set theory and first-order predicate logic. It's worth your time to
understand that, and you might as well work with an author who wants
you to.  

BTW, SQL is more standardized than some give it credit for.  While it's
true that a given statement may be accepted by one DBMS and not
another, a great swath of the language -- all the important parts --
work just fine.  It's quite rare to find two implementations that both
accept a standard query and produce different results from the same
data.  

Have fun storming the castle.  

--jkl



_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if it wasn't tragic...

Warren Young
On Jun 26, 2019, at 3:31 PM, James K. Lowden <[hidden email]> wrote:
>
> You won't find many examples included with your C compiler

That depends a lot on the C compiler in question.  Some C compilers include a *lot* of examples.

Arguably, K&R is a bound book of examples for the AT&T Unix C compiler.  Where is the K&R of SQLite?  I don’t necessarily mean a bound book, but something that’s comprehensive, concise, and tutorial in nature.  I want it.

Microsoft has done a great job with its MSDN site, with an example on almost every function’s page, often in multiple programming languages.  SQLite’s docs aren’t quite at the MSDN level.

SQLite’s docs are far from “tragic.”  You want tragic, take a look at what you get for C++ on a Linux box, where “man std::string” either gives you nothin’ or an auto-generated mess that’s a far cry from what you get from, say, cppreference.com.

But we can do better.  Always.

> or ODBC driver, either.

Not a good example.  An ODBC driver is a thin interface to a particular DBMS, so its docs only need to cover things it adds to the DBMS proper, like its connection string format.  Everything else the ODBC driver should leave to the DBMS’ own docs.

It would be wrong for a SQLite ODBC driver to fully document SQLite.

> Anyone who's done a lot of writing, especially technical writing IMO,
> has the problem of deciding what to include and what to exclude.

Yes.  And as one who’s written a lot of technical documentation, I find that docs are never comprehensive when originally written, or even until years after the first version is “finished.”  The user docs are always a work in continual progress until well after the system they document stops evolving.  As long as the system continues to evolve, the user docs should be an ongoing dialog between the user community and the developers behind the system.

> SQL examples in SQLite documentation, except where they illustrate some
> preculiar aspect of SQLite's SQL, would be only so much noise

Yes and no.

Yes, the SQLite docs need to illustrate its peculiarities, as I’ve previously argued.

But there’s also no reason to expect that SQLite’s docs will expand to be a complete SQL tutorial or noise to its readers.  That’s under our control.

The SQLite docs can also act like K&R did for C, showing good style and thereby influencing its community’s social and technical development.  Once one has read the SQLite docs cover-to-cover, so to speak, one should be a competent user of SQLite, well past the pidgin SQL level.

But just as K&R didn’t close off the market for C books, the SQLite manual doesn’t have to cover **everything** or descend into a mass of irrelevancy.

If you leave people to develop their SQL skills elsewhere, you end up with a big gap between the “SELECT * FROM ContentOfWorld” fans — 185 columns wide — and the “SQL for Smarties” crowd.

> they
> would hinder the job of understanding the grammar.  Necessarily, being
> examples, they would highlight only certain features of the grammar.  

I disagree.  Show someone how to navigate a few laps around the racetrack diagram, and they’ll be better able to plan out their own custom paths around the track.

Such docs show you what’s possible, which influences what you try next.

There’s a lot of content on YouTube showing people how to play various games, and it makes people better gamers.  Someone doesn’t become a master just by watching videos, but a good video expands the viewer’s horizons, making them consider strategies they wouldn’t come up with on their own.

I’ve seen the same basic pedagogical technique used for Vim.  Someone shows you a technique they’ve come up with and this text editor you’ve been using for decades gets a new-to-you feature that you suddenly find essential.  Tutor: “map <F2> !}fmt -w72<CR>”  Student: “That’s awesome!”

I want that for SQLite, too.

> I started learning SQL before Bill Gates discovered the Internet.

I may have started at about the same time, but I stayed at the pidgin SQL level for waaaay too long.

I suspect there’s a lot of really inefficient SQL in the world, and that you’d raise the global tide level higher with some well-considered examples on the SQLite pages than the same amount of effort spent telling people to go read Date.

I want to come away astonished each time I dip into the SQLite docs.  “SQLite can do *that*?  Wow!”

I do sometimes come away astonished already.  I just want it to happen so reliably that I come to expect it.

There are some really special books in the world like that, which take 10 minutes to get through a page, yet never bore the reader, because they’re simply *dense* with great info.  SQLite’s reference manual could be that way.

> Avoid, if I may suggest, anything that promises to make SQL easy or
> implies that it's hard.  It's not hard.  But it may well be the only
> language you ever use that is grounded in math & logic.

Hands-on always beats theory-first as a pedagogical technique for beginners, wherever applicable:

1. Show someone how to get a well-focused task done.

2. Have them try it on their own on their problem set.

3. Have them expand that idea to their next task.  They’ll run into walls, then go to the docs, then expand their horizons, bit by bit.

…weeks and months go by…

42. Study theory to refine techniques built up in the prior several dozen steps.

That’s more true in software development than in any other field I can think of at the moment, because software is so inherently plastic and rewindable.  You don’t get that option in all fields — say, nuclear power plant design — but we’ve got a beautiful thing here in this field.  There’s no reason to insist on theory-first here.

I’d bet that more people know what functional programming is these days because of Javascript than because of ML, Scheme, Erlang, and Haskell combined.  It doesn’t matter that Javascript doesn’t tick all the academic FP boxes, or that common Javascript tutorials don’t really focus on classical FP techniques.  People absorb the concepts anyway, so that when you show an experienced JS programmer “real” FP, they go “Yeah, what’s the big deal?  I’ve been doing that for years!”

That JS programmer can now benefit from knowing the theory, whereas the theory beforehand would’ve likely just been noise to them.

> BTW, SQL is more standardized than some give it credit for.

It’s also the case that once you get outside of that standard core — which is large, granted — you get into code that may run on only one or two popular DBMSes.  I think we agree that writing standard SQL wherever possible is a great idea, but oh those proprietary features…so tempting!

People will find docs on those proprietary techniques when they go searching, so the SQLite docs should have info guiding people back into the ANSI SQL 92 core.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

Keith Medcalf
In reply to this post by ajm

On Wednesday, 26 June, 2019 10:59, [hidden email] wrote:

>Irreproachable argumentation, which in my humble opinion is little or
>nothing useful to those who want to enter in the diabolic world of
>SQL. Especially, if you have not yet managed to change the chip and
>find out that for example, you must carry out a program without using
>variables.

What programming language are you using that does not have variables?  Seems rather unlikely to me that a programming language would not have some sort of concept of "variables", whether those "variables" refer to the storage location of the data itself in memory or are referents (pointers) to data stored in memory.

Could you please expand on what programming language you are referring to that does not have variables -- I find this quite intoxicating!

>All the programming gurus I've read, agree that the best way to
>master a language (SQL is) is to read code from good programmers and
>I do not remember anyone who says that you ask in the forums when you
>have any questions, and the sad reality is that it is difficult to
>find examples of SQL, apart from being attentive to these pages where
>sometimes you learn a lot in the code of some answers.

One does not program in SQL.  One programs in a programming language (COBOL, FORTRAN, BASIC, Assembler, PL/1, C) or some variant of a programming language designed by huxters (C++, C#, Java, IronOxide, etc).

SQL is *S*tructured *Q*uery *L*anguage.  It is what you use inside a programming language to get and put data between main-memory and your storage system (for example, a disk file).  It is not a language in its own right.  Though many large $$$$$$ RDBMS systems which use SQL have wrapped their own internal scripting language into their product -- that is not SQL.  Even the names of these things are different:  PL/SQL, Transact-SQL, SQL.NET, and so on and so forth.  These variants of SQL are related to SQL in the same way as Cherry Code is related to Coke.  They sound similar to the proletariat, but they are not the same.

--
The fact that there's a Highway to Hell but only a Stairway to Heaven says a lot about anticipated traffic volume.



_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
ajm
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

ajm
In reply to this post by Ben Earhart
I must apologize, because I feel that muy comment has been misinterpreted, proably because my weak english.

I did not mean to say that "out there" there are not zillions of books, tutorials, SQL examples, but:

I refer to information "close" to the point where the doubt occurs. In the case of the O.P., in the interpretation of the syntax of certain SQL statement in the SQLite dialect.

In the previous circumstance, finding applicable examples can be an excessively long and painful task, with the aggravating circumstance that the novice must be able to "expurgate" everything that is not directly applicable to the dialect he intends to use.

When I refer to the lack of variables, I mean that in SQL you can't do some like Y = some-sintax, an *later*, do Z = Y + some-sentence. IMHO this is a hard part to start using SQL. At least as hard as prescind to use gotos (yes I also started in this with bow and arrow :-)

 If this had been a technical or theoretical issue, I would probably have refrained from expressing my opinion, due to my lack of adequate preparation. But I think this thread turn around the complain of a beginner, who -I think- has his 2 cts. of reason.

I think that answering with technical delicacies about the léxical domain of SQLite and its doc, helps little or nothing. For example, who can argue that SQLite is not a language but an RDBMS? Of course with the small detail that it uses a particular dialect of the SQL language and we were talking about just that.

Ok. Ok. SQL is not a languaje, but a CLI to interrogate a RDBMS.

That sadid, of course, D.R. Hipp has al the rigth to maintain his doc as criptic as the Dr. Stroustrup in his famous TC++PL book, and consequently, everyone who approaches must come properly cryed from home.

_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if itwasn't tragic...

R Smith-2
On 2019/06/27 10:57 AM, Adolfo J. Millan wrote:
> I must apologize, because I feel that muy comment has been misinterpreted, proably because my weak english.
>
> ...
>   If this had been a technical or theoretical issue, I would probably have refrained from expressing my opinion, due to my lack of adequate preparation. But I think this thread turn around the complain of a beginner, who -I think- has his 2 cts. of reason.

I don't think anyone complained of the OP, we just tried to explain why
the types of documentation he argued for isn't in sqlite, or that
sqlite.org isn't the optimal place for it.

Since then some others have had a bit of backlash. I mean, for one, is
it not enough that the people (who make sqlite) put endless hours into
making one of the best RDBMS engines?, why must they also carry the
torch in the SQL education department? For another, the sqlite devs
probably understand SQL very well, but they won't be in any way more apt
at educating this to (especially) beginners. In fact Richard has claimed
so himself, and I imagine making sqlite takes up most of their time, so 
they typically do not write much user systems or get into contact with
"real-world" query examples (perhaps some via the forum).

I like Warren's idea of a community documentation part, though in the
current way SQLite docs are compiled and produced won't fit such an
ideology - but perhaps we could set up an SQLite-SQL community Wiki on
the side?

I am happy to host this, I'm sure others are too. I am however
unconvinced it will get any real visitors/contributors, even with a
direct link from the sqlite.org front-page. It's the premise that these
things "are needed because they are scarce on the internet" that is
demonstrably false.


> That sadid, of course, D.R. Hipp has al the rigth to maintain his doc as criptic as the Dr. Stroustrup in his famous TC++PL book, and consequently, everyone who approaches must come properly cryed from home.

I don't think the docs are cryptic - they are perhaps less expansive and
aims at getting the truth of a functionality across in the most succinct
way - something that is very much appreciated by any expert user who has
had to wade through pages of crud to find a bit of knowledge (which is
the case in almost every blog). Sure enough there is a place for the
hand-holdy step-by-step type children's books, and they really do exist
(W3Schools and Tynker are great examples - I use it myself when learning
a new thing), but a technical sqilte doc is no place for that.


Not a complaint, just my 2c.  :)


_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
ajm
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good ifitwasn't tragic...

ajm
From R Smith <[hidden email]>:

>Since then some others have had a bit of backlash. I mean, for one, is
it not enough that the people (who make sqlite) put endless hours into
making one of the best RDBMS engines?, why must they also carry the
torch in the SQL education department?

Absolutely agree; perhaps the question would be build some kind of second-level documentation, linked with every page of the first-level/official doc, were the contributors would put his comments, clarifications and examples of code. So, the SQLite team only has to do a certain level of moderation, or even the rest of contributors at the Stackoverflow manner.

>I like Warren's idea of a community documentation part, though in the
current way SQLite docs are compiled and produced won't fit such an
ideology - but perhaps we could set up an SQLite-SQL community Wiki on
the side?

I like the idea too, and respect to there would be real contributors, I'm unsure, but would like to see the result. I'm optimistic in that  point.

>I don't think the docs are cryptic - they are perhaps less expansive and
aims at getting the truth of a functionality across in the most succinct
way - something that is very much appreciated by any expert user who has
had to wade through pages of crud to find a bit of knowledge (which is
the case in almost every blog).

My comment referring to the Sroupstrup's TC++PL languaje vas a joke. Indeed, I find the SQLite doc very well explained and concise, despite the fact that in some points comments and code examples, would be appreciated in a second-level that don't disturb to the expert.

_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if it wasn't tragic...

_ph_
In reply to this post by Ben Earhart
For your second point: it is a reference, not a tutorial. For gentler
introduction, you might want to go to http://www.sqlitetutorial.net/


First and foremost, though, itis one of the best documentations I've worked
with. Yes, it's wordy, but it's not verbose. It's precise and aims for
formal correctness, making it very much non-ambigous.

Yes, the habit of writing in full sentences makes it an unusual read, but
after using it as a foundation for a large, long-running project, I'm deeply
thankful for its existence.






--
Sent from: http://sqlite.1065341.n5.nabble.com/
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: the sqlite3 documentation would be pretty good if it wasn't tragic...

Jens Alfke-2
In reply to this post by Warren Young


> On Jun 26, 2019, at 3:39 PM, Warren Young <[hidden email]> wrote:
>
> Arguably, K&R is a bound book of examples for the AT&T Unix C compiler.  

It was also the _first_ book on the C language.

> Where is the K&R of SQLite?  I don’t necessarily mean a bound book, but something that’s comprehensive, concise, and tutorial in nature.  I want it.

There are several books focusing on SQLite. I have a pretty good one from O'Reilly somewhere. There is probably a website somewhere that has a search field where you can type "SQLite" and find a list of books. Maybe such a site could even ship you a book.

> Microsoft has done a great job with its MSDN site, with an example on almost every function’s page, often in multiple programming languages.  SQLite’s docs aren’t quite at the MSDN level.

Microsoft is one of the largest companies in the world, and must certainly have thousands of tech writers and editors.

SQLite has, AFAIK, _two_ employees (Richard and Dan). Both of them are coders. Asking them to put part of their time into writing SQL examples would be tragic. And they probably don't have the money to hire tech writers.

—Jens
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
12