Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Searching for julia documentation on search engines is not convenient. Separate documentation page for each Base and stdlib function #29552

Open
ViralBShah opened this issue Oct 7, 2018 · 4 comments
Labels
docsystem The documentation building system

Comments

@ViralBShah
Copy link
Member

ViralBShah commented Oct 7, 2018

Currently, our API reference lists several groups of functions on one page. Example:
https://docs.julialang.org/en/v1/base/math/

This leads to very long html pages. Often a common way to find help is by using a search engine with a search term like julia lufact and you do end up finding the right page. On Google, it currently points one to the linear algebra documentation:
https://docs.julialang.org/en/v0.6.2/stdlib/linalg/

Now, one has to search for lufact on that page, and only the 4th mention of lufact there actually takes you to the actual documentation. Instead, if we had documentation of each API on its own page, it would be a lot more useful.

In Python, for example, searching python lu gives:
https://docs.scipy.org/doc/scipy-0.13.0/reference/generated/scipy.linalg.lu.html

And similarly, R lu gives:
https://stat.ethz.ch/R-manual/R-devel/library/Matrix/html/LU-class.html

I believe that the python and R experience here is much nicer. Significant work may need to be done on the doc system to make this happen, with all the navigation improvements to make it work well. I thought it would be worth having an open issue for someone who wanted to dive into the documentation improvements, or for a potential GSoC project.

@ViralBShah ViralBShah added the docsystem The documentation building system label Oct 7, 2018
@vtjnash vtjnash added the Hacktoberfest Good for Hacktoberfest participants label Oct 9, 2018
@ViralBShah ViralBShah changed the title Separate documentation page for each Base and stdlib function Searching for julia documentation on search engines is not convenient. Separate documentation page for each Base and stdlib function Apr 13, 2019
@ViralBShah
Copy link
Member Author

ViralBShah commented Apr 13, 2019

Searching for eigvals on Google leads one to end up on the top of the entire linalg API. What you want is this to land directly on the eigvals documentation.

Similar results for search on Bing, but it also actually finds jlhub.com (3rd hit) that seems to do the right thing.

http://www.jlhub.com/julia/manual/en/function/eigvals

@ViralBShah
Copy link
Member Author

Should this issue be filed in Documenter.jl?

@Ellipse0934
Copy link
Contributor

There is another point to be made here. After googling when the user does reach the lufact page it is for v0.6.2 not the stable release. Naturally the user will use the dropdown on the left to click on v1.1 but that leads to introduction page of v1.1 not the corresponding linalg page.
What could be done is check if a corresponding page exists for v1.1 then redirect there or else redirect to base. Might be inaccurate at times but I feel that's better than leading to the root.

@logankilpatrick
Copy link
Member

I’ve thought about this a lot and was always puzzled that when I searched things, I never saw the Julia docs in the search results whereas with python I often times find myself being taken to their docs during a search. If this isn’t done by this coming spring, I will apply to GSoC with this project.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docsystem The documentation building system
Projects
None yet
Development

No branches or pull requests

5 participants