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
