Can we change the ruby on rails website documentation?

The Ruby on rails documentation is really hard to navigate, its a lot of stuff and everything is everywhere and I cant find what I’m looking. Hoping for new Upgrade documentations like the documentation used by vuejs or nuxt4.

1 Like

I got accidentally involved with recommending and using a static site generator for prog lang community marketing / community / tutorial website last year. At that time, I was leaning towards 11ty, as it stays with static html, but let’s you use all the html and markdown libraries on npm. I originally wanted to choose hugo, so that I could avoid depending on npm world. I ended up choosing nextjs to accommodate other peoples’ desire to have more interactivity and javascript.

I would probably choose docusaurus v2 for a site that only had tutorials and didn’t need marketing or community pages. I don’t like npm, but since a large chunk of the dev world is using javascript to create html and css for single page apps as well as for markdown rendering, it feels like you have the access to the largest potential set of markdown and html libraries with npm (rather than static site tools using go, python, ruby). I liked 11ty’s philosophy, but docusaurus has a nice set of built in features for documentation. Docusaurus v2 uses the complex hydration with client side interactivity which 11ty shuns, but it’s probably worth dealing with it.

1 Like

I really don’t care what framework to use, the most important is to make users or even new users to easily navigate in the documentation. Before the current guide is not that really good.

1 Like

I haven’t formed an opinion on the current navigation yet.

I agree that framework doesn’t matter too much, as long as it won’t go obsolete too fast. I mentioned the framework because I imagine the first step in writing new docs and building nav would be selecting some directory organization and creating markdown files, and once you pick a framework, you can start working on those according to the framework’s organization rules.