From: Matous Jan Fialka <mjf@mjf.cz>
To: pgsql-docs@lists.postgresql.org
Cc: wolakk@gmail.com
Subject: Tutorial book with runable code for Postgres?
Date: Tue, 29 Nov 2022 09:40:47 +0100
Message-ID: <80cfa3b61c0c733f1afad01a776375ec@mjf.cz> (raw)
In-Reply-To: <166608103231.2042183.13992576112735261253@wrigleys.postgresql.org>
References: <166608103231.2042183.13992576112735261253@wrigleys.postgresql.org>
Hello.
I would like to get some opinion on a petite idea I got while reading
the "nextval
parameter is not clear" thread. Because it may not fit well to the
thread itself
I managed to create a new one instead...
I started to love the way "rustaceans" do their documentation - they
produce books
with runable examples! Perhaps it would be nice to adopt their approach
for new and
shiny tutorial book and place (runable?) examples there. The official
documentation
could refer to proper tutorial sections and vice versa. Also, the
tutorial can be
more or less structured the same as it is the official documentation
(the two documents
can be more or less aligned, at least "vaguely").
The very best example of the approach of a book with runable examples
is the
"The Rust Programming Language" [1][2] aka "The Book". Who has not
known about it,
please give it few minutes to see how it works and what a great
experience it is
to read it. :-)
I am not sure how hard it would be to fork the mdBook project [3] and
add
Postgres psql(1), SQL and perhaps PL/PgSQL syntax highlighting with all
the nifty features such as the "snippets" etc. (some code is
intentionaly
hidden while the reader is beying forced to concentrate at just part of
it,
but still allowed to show the hidden code if she is in need of it). As
I understand
the mdBook project is general framework to generate such documentations
and therefor
I suppose it is extensible in some rather sane way.
I am also not aware if DB Fiddle or another service allows to run
examples covered
in such tutorial book via some API or not. If not, the results could
still be
"pregenerated" and hardcoded at compile time. Maybe, in this case, it
would be even
better.
There are good ways and bad ways how to do things and the learning
curve is not
always steep enough. As a novice DBA you sometimes follow the wrong
path for quite
a long time! Good tutorial (expecially with runable examples) will be
definitely
worth the effort. It should also include good amount of all sorts of
errors and warnings
that are also very hard to comprehend! It should provide all sorts of
"NoGo" things
and approaches explained in depth and followed by a couple of "Go"
ones.
References:
[1] https://doc.rust-lang.org/book/
[2] https://github.com/rust-lang/book (source code of "the book")
[3] https://rust-lang.github.io/mdBook/format/mdbook.html
Best regards,
--
Matous Jan Fialka
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: mjf@mjf.cz, pgsql-docs@lists.postgresql.org, wolakk@gmail.com
Subject: Re: Tutorial book with runable code for Postgres?
In-Reply-To: <80cfa3b61c0c733f1afad01a776375ec@mjf.cz>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox