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.
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.
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.
I enjoyed the Guide, so I’m probably biased. What exactly were you looking for and didn’t find?
I was actually able to find what I’m looking, but to be able to go to different pages, the page needs to reload.
I mean the guide is fine, its actually easy to use but the time it reloads when going to different pages.
FWIW, Rails guides and APIs are statically generated and served by NGINX. We even generate the compressed versions in the file system for NGINX to serve directly (
It will help a lot if there is a search box at the top
Yup I think that is also a good suggestion.
So what you were looking for is actually Single-Page Application (SPA). I’m not sure how difficult it is to generate an SPA from the current Guide, but I myself enjoys the simplicity of static websites. For any one who plan to build SPA, I suggest:
- Do it right, the first time. Accessibility needs to be implemented in SPA, while for static websites the browser did most thing correctly. An example: most navigation should behave like “links”, e.g. I can “open in a new tab”, or hover my mouse on the link to preview the target URL.
By the way, what’s “nuxt4”? I only found Nuxt3.
yeah, I agree with your points, I would probably like to volunteer but I am so busy on my current Job.
wait, nuxt4? I think their is no nuxt4 yet. Nuxt3 is still on RC.
There is a PR to add search to Rails Guides:
Transitioning the guides site to SPA doesn’t bring any additional value to the guides site, my preference would be to keep it as @fxn mentions. SPA is just going to add more tooling for effectively the same result that’s currently there, a page refresh is fine. This is also what vuejs and nuxt4 do as well, statically generated pages.
Adding search would be helpful though, I agree on that one.
Algolia opened a PR a while back and we had a discussion.
I have paid for the servers that host Rails documentation and Rails Contributors since I purchased them many years ago. Why? Because it is fair that if you get help from a company, you give credit for it, for example with a logo. OK, I don’t want to push brands into the minds of Rails programmers, so I solved this personal dilemma with money.
So, the summary of the PR was: That’d be nice, as long as there’s no branding. They said, but branding is fair, and I said, yes, but I did not ask for this patch, I am only saying under which conditions it would be accepted. And that was the end of it.
Now, I don’t pay for the servers anymore, so whether to go for that solution or not I leave to the rest of the core team that might be interested in this and if they go with that solution it’ll be fine with me.
@fxn Ah gotcha, good to know. Are the servers running PG? I’d assume not and it’s just nginx serving up those files. Is the deploy process something along the lines of a
git pull and then
We have a webhook in GitHub that triggers an action in the docs server on every push.
That action then updates the local checkout, generates edge docs (API and guides), if a new stable tag version is detected, generates stable docs for that release (API and guides). Also, Rails Contributors updates.
Documentation is compressed HTML files on disk served by NGINX, no database.
@fxn Is the PR above feasible? Is execjs available at build time already? I noticed that’s required in the new search_index.rb file.