How-to Guides for JBang

[wfouche]

Today I discovered (by accident) that JBang makes it easy to run JMH benchmarks.

https://xam.dk/blog/jbang-reproducers/

This is an amazing use case for JBang, and it got me wondering what other JBang gems have I not yet discovered?

To make it easier for users to discover what can be accomplished with JBang, I think we should create How-to Guides for JBang.

How-to guides could be a seperate chapter at the end of the JBang user guide.

JBang
├── Intro
├── Installation
├── Usage
├── ....
CLI Reference
├── jbang
│   ├── run
│   ├── build
│   └── ....
How-to Guides
├── JMH and Async Profiling
├── ....
└── ....

How-to guides will promote the use of JBang and help users to unlock its full potential.

• https://docs.divio.com/documentation-system/how-to-guides/

@maxandersen , @quintesse - what do you think of this proposal?

[quintesse]

Sure, seems like a good idea
Would be nice to have more than one, though.

And @maxandersen , perhaps that blog should be updated. The PR you talk about was accepted after all.
And if you tell it to use a more modern Java version you can get rid of the --preview flag. (And I'd always use the + version, no use in forcing a download of a specific Java version if one has an even newer version installed)

[wfouche]

JBang Cookbook is an alternative name that can be used.

[maxandersen]

I would love for something like that - I've done a bunch of them myself and always wondered where best to put them.

this idea of adding a cookbook or jbang recipe seems as good an ideas any other :)

[wfouche]

JBang and Docker example

• https://gist.github.com/maxandersen/f077f1d356c42eeb395a8811d6152f3a

[maxandersen]

using jbang with tools like jdeprscan: https://www.reddit.com/r/java/comments/1llrjp9/comment/n07k0ok/

[wfouche]

[wfouche]

Looking at what Scala-CLI does with their documentation, the Cookbook is in the main documentation set.

https://scala-cli.virtuslab.org/docs/cookbooks/intro/

Will search for more examples. My preference in the long run would be to have it in the Antora set, so that new users can easily find cookbook "recipies" via Antora search.

[wfouche]

I just remembered the 4 quadrant documentation model.

https://docs.divio.com/documentation-system/

Several documentation sites are structured in this way, and a "Cookbook of technical recipes" is just a "How-to Guide"

One could always start small and incubate the recipes in jbang-examples and then when there are enough of them and they are tried and tested decide whether to convert them to an Antora Cookbook / How-to Guide. Some of the recipes might need some time to mature in private.

[wfouche]

We should pin the jbang-examples repo then it would be easier to find / discover it.

Four repos are currently pinned, Github allows up to six repos to be pinned.

Another How-to Guide example

• https://docs.spring.io/spring-boot/how-to/index.html

[maxandersen]

The search should cover it all - are you seeing some being missed ?

[wfouche]

The search is working fine, but the pinned repos are the popular once that should be in the "shop window" for passersby to see and discover. That's why I think jbang-examples should be pinned.

[wfouche]

I think cookbook recipes should rather be hosted in a new repository called jbang-cookbook, from which stable branches can be created from where the Antora pages and JBang scripts can be sourced from.