pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedTutorial book with runable code for Postgres?
4+ messages / 3 participants
[nested] [flat]
* Tutorial book with runable code for Postgres?
@ 2022-11-29 08:40 Matous Jan Fialka <mjf@mjf.cz>
2022-11-29 21:42 ` Re: Tutorial book with runable code for Postgres? Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: Matous Jan Fialka @ 2022-11-29 08:40 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: wolakk@gmail.com
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
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Tutorial book with runable code for Postgres?
2022-11-29 08:40 Tutorial book with runable code for Postgres? Matous Jan Fialka <mjf@mjf.cz>
@ 2022-11-29 21:42 ` Kirk Wolak <wolakk@gmail.com>
2022-11-29 22:15 ` Re: Tutorial book with runable code for Postgres? David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: Kirk Wolak @ 2022-11-29 21:42 UTC (permalink / raw)
To: mjf@mjf.cz; +Cc: pgsql-docs@lists.postgresql.org
On Tue, Nov 29, 2022 at 3:40 AM Matous Jan Fialka <mjf@mjf.cz> wrote:
> 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...
>
> +1 (right approach, I was clearly wrong, learning...)
> ...
> 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 actually recorded this interaction. I think this is cool.
And as I think about WHERE this goes, I DEFINITELY believe it goes
in the tutorial world. I love the "peek" and the "play" icons, on mouse
over.
https://app.screencast.com/VddQpV2LYoUdx
for those that want to see it themselves:
https://rust-lang.github.io/mdBook/format/mdbook.html
And scroll to the bottom of that page.
> ...
> 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.
>
>
If in the tutorial we used this "hiding" technique to explain the code,
but expanded it so it was runnable, that would be awesome.
I like the idea of it being able to go directly to:
https://www.db-fiddle.com/
to either a specific preloaded example, or better, pass in our code...
Especially if we could do it using one CSS/Javascript wrapper!
>
> 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
> --
> Matous Jan Fialka
>
Thanks... Let's hope the discussion gets some traction...
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Tutorial book with runable code for Postgres?
2022-11-29 08:40 Tutorial book with runable code for Postgres? Matous Jan Fialka <mjf@mjf.cz>
2022-11-29 21:42 ` Re: Tutorial book with runable code for Postgres? Kirk Wolak <wolakk@gmail.com>
@ 2022-11-29 22:15 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-29 22:40 ` Re: Tutorial book with runable code for Postgres? Kirk Wolak <wolakk@gmail.com>
0 siblings, 1 reply; 4+ messages in thread
From: David G. Johnston @ 2022-11-29 22:15 UTC (permalink / raw)
To: Kirk Wolak <wolakk@gmail.com>; +Cc: mjf@mjf.cz; pgsql-docs@lists.postgresql.org
On Tue, Nov 29, 2022 at 2:42 PM Kirk Wolak <wolakk@gmail.com> wrote:
> On Tue, Nov 29, 2022 at 3:40 AM Matous Jan Fialka <mjf@mjf.cz> wrote:
>
>> 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...
>>
>> +1 (right approach, I was clearly wrong, learning...)
>
>> ...
>> 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 actually recorded this interaction. I think this is cool.
> And as I think about WHERE this goes, I DEFINITELY believe it goes
> in the tutorial world. I love the "peek" and the "play" icons, on mouse
> over.
> https://app.screencast.com/VddQpV2LYoUdx
>
> for those that want to see it themselves:
> https://rust-lang.github.io/mdBook/format/mdbook.html
>
>
Haven't dived into these things yet - but I had the thought that maybe the
tutorial section of our documentation is not a good place for this. Nor,
frankly, do I think sgml be a great technology from which to try and
leverage this. Hosting a second "site", and git repository, geared toward
this kind of effort, seems like a reasonable thing to do. It doesn't need,
nor want, the same versioning and releases cadence policies as the
documentation.
I think the main question is, if that were the intended route, how much
material would we consider a minimum viable release (done elsewhere
probably) to go to the effort to get the infrastructure in place to host
long term - i.e., after the initial novelty wears off and committers have
to take on ownership? Specifically, require that at minimum the tutorial
section of the documentation be removed from the documentation and instead
the same material, ideally improved, placed in this new location with the
new design goals and requirements published.
We'd get rid of any output formats except HTML (no PDF or man pages).
Cross-references would still be desirable and so a plan for those (done as
part of the tutorial migration) would be required. There wouldn't be any
"older version support" either IMO, just one main release branch.
IOW, I have my doubts regarding the success of a project to retrofit the
tutorial to this extent. I don't think teaching the old dog these new
tricks is going to go well.
I do like the idea of having a place where people who want to produce this
kind of stuff, but not write an entire book or tutorial, or try and market
their own blog, can find a home to publish.
I'm not too keen on worrying about "auto-execute" - if anything, convincing
the reader to physically type any example code into a fiddle, or their own
installation, is a better idea - even to the extent of removing
copy-paste...
Any automation or tests that would help ensure the published material is
valid should be done during "build" using psql.
David J.
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Tutorial book with runable code for Postgres?
2022-11-29 08:40 Tutorial book with runable code for Postgres? Matous Jan Fialka <mjf@mjf.cz>
2022-11-29 21:42 ` Re: Tutorial book with runable code for Postgres? Kirk Wolak <wolakk@gmail.com>
2022-11-29 22:15 ` Re: Tutorial book with runable code for Postgres? David G. Johnston <david.g.johnston@gmail.com>
@ 2022-11-29 22:40 ` Kirk Wolak <wolakk@gmail.com>
0 siblings, 0 replies; 4+ messages in thread
From: Kirk Wolak @ 2022-11-29 22:40 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: mjf@mjf.cz; pgsql-docs@lists.postgresql.org
On Tue, Nov 29, 2022 at 5:16 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:
> On Tue, Nov 29, 2022 at 2:42 PM Kirk Wolak <wolakk@gmail.com> wrote:
>
>> On Tue, Nov 29, 2022 at 3:40 AM Matous Jan Fialka <mjf@mjf.cz> wrote:
>>
>>> 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...
>>>
>>> +1 (right approach, I was clearly wrong, learning...)
>>
>>> ...
>>> 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 actually recorded this interaction. I think this is cool.
>> And as I think about WHERE this goes, I DEFINITELY believe it goes
>> in the tutorial world. I love the "peek" and the "play" icons, on mouse
>> over.
>> https://app.screencast.com/VddQpV2LYoUdx
>>
>> for those that want to see it themselves:
>> https://rust-lang.github.io/mdBook/format/mdbook.html
>>
>>
> Haven't dived into these things yet - but I had the thought that maybe the
> tutorial section of our documentation is not a good place for this. Nor,
> frankly, do I think sgml be a great technology from which to try and
> leverage this. Hosting a second "site", and git repository, geared toward
> this kind of effort, seems like a reasonable thing to do. It doesn't need,
> nor want, the same versioning and releases cadence policies as the
> documentation.
>
> I think the main question is, if that were the intended route, how much
> material would we consider a minimum viable release (done elsewhere
> probably) to go to the effort to get the infrastructure in place to host
> long term - i.e., after the initial novelty wears off and committers have
> to take on ownership? Specifically, require that at minimum the tutorial
> section of the documentation be removed from the documentation and instead
> the same material, ideally improved, placed in this new location with the
> new design goals and requirements published.
>
> We'd get rid of any output formats except HTML (no PDF or man pages).
> Cross-references would still be desirable and so a plan for those (done as
> part of the tutorial migration) would be required. There wouldn't be any
> "older version support" either IMO, just one main release branch.
>
> IOW, I have my doubts regarding the success of a project to retrofit the
> tutorial to this extent. I don't think teaching the old dog these new
> tricks is going to go well.
>
> I do like the idea of having a place where people who want to produce this
> kind of stuff, but not write an entire book or tutorial, or try and market
> their own blog, can find a home to publish.
>
> I'm not too keen on worrying about "auto-execute" - if anything,
> convincing the reader to physically type any example code into a fiddle, or
> their own installation, is a better idea - even to the extent of removing
> copy-paste...
>
> Any automation or tests that would help ensure the published material is
> valid should be done during "build" using psql.
>
> David J.
>
>
David, I don't disagree. This process has been an education process for
me.
I actually like the idea of a github account for a postgresql tutorial.
It could come out of here, and we could potentially have those that are
interested chime in. (Although I would like to occasionally email into
this group to ask them to peek and give feedback, looking for that point
where we can say it is ready for V1.00 (and PG may refer to it as a
replacement for the tutorial they have).
I can think of a few people that might lend a hand (that may have warned
me not to get my hopes up here... LOL)
And yes, then that site doesn't need to be a PDF... And starting with the
existing Tutorial stuff, and then maybe
a simple cross reference (coverage) of the various functions, etc.
Maybe Matous [OP] will contact me externally...
regards, Kirk
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2022-11-29 22:40 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-11-29 08:40 Tutorial book with runable code for Postgres? Matous Jan Fialka <mjf@mjf.cz>
2022-11-29 21:42 ` Kirk Wolak <wolakk@gmail.com>
2022-11-29 22:15 ` David G. Johnston <david.g.johnston@gmail.com>
2022-11-29 22:40 ` Kirk Wolak <wolakk@gmail.com>
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