Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic...
On the documentation page (https://www.sqlite.org/docs.html) under "Overview Documents" is "Books About SQLite" https://www.sqlite.org/books.html > SQLite has, AFAIK, _two_ employees (Richard and Dan) See: https://www.sqlite.org/crew.html -Original Message- From: sqlite-users On Behalf Of Jens Alfke Sent: Thursday, June 27, 2019 12:31 PM To: SQLite mailing list Subject: Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic... > On Jun 26, 2019, at 3:39 PM, Warren Young 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 sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users ___ sqlite-users mailing list sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic...
> On Jun 26, 2019, at 3:39 PM, Warren Young 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 sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic...
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 sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic...
On Jun 26, 2019, at 3:31 PM, James K. Lowden 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 !}fmt -w72” 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 wy 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 techn
Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic...
On Sat, 22 Jun 2019 23:14:08 -0700 Ben Earhart 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 sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn'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 sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic...
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. 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. 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 sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Re: [sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic...
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 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 > sqlite-users@mailinglists.sqlite.org > http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users > ___ sqlite-users mailing list sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
[sqlite] the sqlite3 documentation would be pretty good if it wasn't tragic...
...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 sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
