Re: Tutorial book with runable code for Postgres?

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.