Re: Tutorial book with runable code for Postgres?

On Tue, Nov 29, 2022 at 5:16 PM David G. Johnston <
david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

> On Tue, Nov 29, 2022 at 2:42 PM Kirk Wolak <wolakk(at)gmail(dot)com> wrote:
>
>> On Tue, Nov 29, 2022 at 3:40 AM Matous Jan Fialka <mjf(at)mjf(dot)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