On Jun 26, 2019, at 3:31 PM, James K. Lowden <jklow...@schemamania.org> 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 sqlite-users@mailinglists.sqlite.org http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
