[Documentation] Rack tutorial

[rubyFeedback]

I found some kind of rack "tutorial" here recently:

https://gist.github.com/markbates/4240848

Naturally it is incomplete; some 13 years ago. People asked for licencing in that gist though.

Anyway. Would it be possible if we could begin to document Rack in a way as
if it were:

a) a tutorial
b) with up-to-date-examples
c) as well as a FAQ?

With google searching being really bad, finding useful documentation has become
really difficult; many things are also outdated now. This also affects some other
projects, such as sinatra, although sinatra has better documentation than rack.
(Roda also has good documentation, but ALL frameworks lack working standalone
examples or assume people conform just to e. g. "use .ru files", as if this really
explains the API much at all.)

Rack has really no documentation at all: We have https://rack.github.io/rack/main/index.html, but
this is a red herring. It looks fancypants "yay, an index.html file a HTML file oh my god, this
is like the oldschool days" - but then you read it, you click on links, and ... it's nothing. Almost
nothing. Please look at it. Tell me anyone has ever read it. It is glorified nothingness.

Now I understand that people may be more likely to use e. g. sinatra, since there is more
documentation there. That's a fair point. Although, sinatra also has a lot of outdated documentation.
Nobody seems to want documentation anymore in ruby land. Perhaps some years ago this was
not so severe a problem, but there are now evidently fewer ruby folks, google search also sucks -
we need better documentation. And I think it should happen on the ground-level already, aka
rack. Granted, perhaps I could or should use sinatra, but I wanted to move away because the
documentation in sinatra is so poor. I am hopping from horrible documentation to even worse
documentation to zero documentation.

Now: as nobody is paid for writing a tutorial, of course I don't expect people to jump out of nowhere
and say "yay, I'm gonna invest 50 hours to write documentation!". That's not realistic, people have
many other things to do - I totally get it. So this is here more of a "can we have a todo-entry and
pursue it in the next ~3 years or so?". Aka first, if people agree on it - this would already be great.
Perhaps this could be documented, so that people could rally around it - like a flag.

There is, then, if approved and agreed, a chicken-egg problem. Where to start? People who know
rack well, may not need to contribute or read up on it, whereas newcomers need a lot of documentation.
I don't have a good solution for this, but perhaps it may help if the main README here could ask
for people to help contribute to a useful tutorial + examples. We could use the wiki perhaps, but
from my experience, only very few people will use the wiki; and when searching for documentation,
the wiki is often ignored. Case in point:

https://github.com/rack/rack/wiki

Last update: 15 years ago. I can feel the decaying bodies in the cellar here.

That actually has a link to:

https://github.com/rack/rack/wiki/Tutorials

Which is a bit better. Last updated 2022 so only 3 years ago. So not quite dead.

Ok so here is hoping I can find USEFUL things.

First link there:

https://lucianopanaro.com/2008/10/15/creating-a-rack-middleware-for-minifying-your-javascript-files.html

Oops does not exist. By the way, 2008 ... 17 years ago, soon 18 years. People, we are living in DEAD TEXT
world now.

We also have the rack specification here:

https://rack.github.io/rack/main/SPEC_rdoc.html

This one is quite nice, but I'd love to have someone work through it and rework it so that newbies and
people who have a hard time acquiring new information - like me - understand it better. Mostly some
formatting stuff and also content, making it easier to read. Anyway, let's go back to the tutorial on the
wiki.

Rackup here is from 2021:

https://github.com/rack/rack/wiki/%28tutorial%29-rackup-howto

It's not bad. It even has this info:

The config file is treated as if it is the body of

app = Rack::Builder.new { … config_file_content_here … }.to_app  

That's quite nice, although a fully working example would be nicer. I don't know
what exactly goes into {} - more explanations would be great, but anyway, at
the least I found something useful down this rabbit hole. But many people probably
will never see it ... I think it would be better to link in to specific subcontent from
the main README. Or, if that is too long, a separate file that is carried in doc/ or
elsewhere. Anyway, that file is quite ok-ish, probably may need to be updated
and extended, but this is something I would expect of a useful tutorial + documentation
guide.

The next link goes to:

https://code.tutsplus.com/exploring-rack--net-32976a

I think it would be better to make this content available on the github-rack page as is,
because otherwise such external websites may vanish and then we lose information.
StackOverflow also has this problem by the way.

https://web.archive.org/web/20200225220612/http://rubylearning.com/blog/2013/04/02/whats-rack/
works but the link is dead. Three other links are also dead. We are decaying information here.

Hmmm. Hopefully I was able to convince a few folks. Can we start with a tutorial that is kept
within rack? I think I also suggested this for sinatra a while ago. Evidently the chicken-egg
problem is difficult to solve; I have no idea how to motivate old experienced folks to help
contribute documentation, but perhaps if the entry-barrier to contribution can be very low,
we may have more folks contribute what they know, right to github rack repository here?

Anyway, I just wanted to give this a try, as I am now facing the dilemma of what to do with
regards to ruby. Ruby is a great language, but life is too short to hope that documentation
becomes better on its own (I understand the "but you should contribute" part, but I don't
know rack, sinatra etc... that well, the things I do are super-simple things usually).