Re: Tutorial book with runable code for Postgres? - Mailing list pgsql-docs

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.