To: <pgsql-docs@lists.postgresql.org>
Subject: Tutorial book with runable code for =?UTF-8?Q?Postgres=3F?=
MIME-Version: 1.0
Content-Type: text/plain;
 charset=UTF-8;
 format=flowed
Content-Transfer-Encoding: 7bit
Date: Tue, 29 Nov 2022 09:40:47 +0100
From: Matous Jan Fialka <mjf@mjf.cz>
Cc: <wolakk@gmail.com>
Organization: MJF
Reply-To: <mjf@mjf.cz>
Mail-Reply-To: <mjf@mjf.cz>
In-Reply-To: 
 <166608103231.2042183.13992576112735261253@wrigleys.postgresql.org>
References: 
 <166608103231.2042183.13992576112735261253@wrigleys.postgresql.org>
Message-ID: <80cfa3b61c0c733f1afad01a776375ec@mjf.cz>
User-Agent: Roundcube Webmail/0.5.3
Archived-At: 
 <https://www.postgresql.org/message-id/80cfa3b61c0c733f1afad01a776375ec%40mjf.cz>
Precedence: bulk

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