It blows my mind that Rails Guides don’t have search built in. Sure I can use site:guides.rubyonrails.org in Google, DuckDuckGo, etc., but that’s a pain. And let’s face it, it’s a bit weird considering the guides are the friendly face of an infinitely flexible web app framework!
Thanks for pointing this out!
While I’m here, the number of “Work in progress” sections in the guides can be a little off-putting. Not so much WTF, but more HTF give the maturity and stability of Rails. Remember, this status means the sections don’t show in the Guides Index either.
Is there any advantage of marking sections as in progress, given that all of the sections are constantly being updated?
That mark is being used internally for guides that were never published neither reviewed by the documentation team. Those guides are incomplete or wrong, so a point could be made to not even show them in the website.
I can see why for example the ActionText documentation is “Work In Progress” but I’m not sure why “Action View Overview” is still WIP. I’d like to help making it non-WIP.
It does seem silly I only go to rails guides for overviews and the occasional google result - but for every day I use Ruby on Rails - APIdock .
Right - that is exactly my point. Because it is well indexed and searchable, I rely on API Dock instead of the rails guides or API docs. In my ideal magical world, I would go to the official pages and they would all be well indexed, well integrated, and very searchable.
And, ideally, commentable like API dock is - because that is also super useful.
I love the commentable feature. It feels like PHP documentation in the old days. You’ll learn a lot just from the comments
+100 could we please add a search and bring the useful stuff from APIdock, is painfully slow to search anything, but is the only good place we have now (unless we improve the oficial)
I would be happy to help set up DocSearch in rails guides!
DocSearch: Search made for documentation
Thanks for not including algolia search. There is a trully open source alternative called Lunr.js
Should we consider that?
Thanks @fxn I was not aware of this discussion.
Another alternative would be to use an Elasticsearch instance and index the guides contents as part of the build process, then run searches from the frontend against Elasticsearch, but I’m not experienced in this approach.
I actually liked this Proof of Concept:
I’d love to help finalize this feature
Aaahh yes! That was the one. Yes, I think that would be nice to investigate. We should revive that proof of concept and see where do we get.
I might be mistaken, but Lunr.js seemd JS based without any back-end components and should work with a static website.
I took a look at it last night and all of the Guides’ markdown is just 2MB, uncompressed. With GZIP + a simple search in JS, you could provide this easily without the need to set up a backend.
Luckily, the guides are not a SPA and we have some spare MBs to download .