(This may not be the best place for this, but wasn’t sure where else to ask)
I’m currently working my way through the Stan User Guide (version 2.18), which is great (and I love the new-ish HTML implementations of them). As I’m going through though, I’m noticing some small typos, or sometimes references to sections that don’t exist (for example, Section 1.2 says “See the reference manual for a definition of the QR-decomposition”, but then the reference manual doesn’t have that definition, as far as I can tell). Is it useful to flag this kind of thing for anyone, and if so, where’s the best place to do it? I’m assuming this forum isn’t the right place. And if it’s not useful to flag these, that’s fine too! Just thought I’d ask.
2 Likes
Good question. Don’t know what’s the preferred way… Maybe directly via GitHub? Actually, the user guide is at version 2.21 right now: https://mc-stan.org/docs/2_21/stan-users-guide/index.html. So make sure you’re not wasting time fixing stuff that’s already fixed. ;) There are still typos formatting issues in the most recent guide, though.
1 Like
That’s good to know (it looks like I was using a cached version of the documentation page without realizing, which took me to version 2.18)! And it looks like this problem is fixed there - though my larger question still stands. Happy to flag it through github if that’s the preferred way.
1 Like
Yeah, when you Google “Stan user guide/functions reference/language reference” the first organic links actually point to old versions respectively, which is kind of unfortunate.
1 Like
This is the current github issue for small correction to the documentation:
If you are posting something there, make sure to mention which document you refer to. It’s also worth checking the most recent version of the docs that are online (currently at 2.21), as many fixes might have been applied already.
5 Likes
Thanks so much! This was exactly what I was looking for.
@mitzimorris is trying to figure out how to make our search results better. Any suggestions are appreciated.
I noticed some projects have official docs under docs/latest or similar. This can improve search results in exchange for a risk of breaking links as the docs are updated…
that doesn’t help the SEO problem - we have “unversioned” links -
e.g.: “https://mc-stan.org/docs/stan-users-guide/index.html”
this redirects to latest by virtue of a script which rewrites the redirects every time we do a release.
either the redirect links aren’t being used anywhere, or else they’re not getting indexed by Google - I think they’re probably not getting used.
But the unversioned link is a redirect, not an alias. AFAIK Google will follow the redirect and index the target page directly. If that was an alias, it should IMHO work… (but if the unversioned links are not used anywhere, that would obviously not help)
don’t understand - we want the redirect behavoir - what do you mean by “alias”?
Google suggests “canonical links” - would this work?
Use rel=“canonical” link tag
You can use a<link>tag in the page header to indicate when a page is a duplicate of another page.Suppose you want
https://example.com/dresses/green-dressesto be the canonical URL, even though a variety of URLs can access this content. Indicate this URL as canonical with these steps:
- Mark all duplicate pages with a rel=“canonical” link element . Add a
<link>element with the attributerel="canonical"to the<head>section of duplicate pages, pointing to the canonical page, like this one:
<link rel="canonical" href="https://example.com/dresses/green-dresses" />
given that we’re dealing with a static site, easy to add this too all the existing pages, and bookdown/gitbook has hooks to put this in the <head> element for future releases.
this should perhaps be its own thread - SEO for docs.
1 Like
The assertion seems to be that if we redirect URL x to URL y, then Google only indexes URL y.
If I search for
stan variable transform
on Google, the URL I get as the first hit displays as
https://mc-stan.org › docs › stan-users-guide › changes-of-variables
But when I look at the URL from the link from Google, you can see the version 2_18 in it:
url=https%3A%2F%2Fmc-stan.org%2Fdocs%2F2_18%2Fstan-users-guide%2Fchanges-of-variables.html
And indeed, clicking on the link takes me to
https://mc-stan.org/docs/2_18/stan-users-guide/changes-of-variables.html
I believe @martinmodrak is suggesting a distinct URL for the latest doc so that the latest doc would itself get indexed rather than the target of the redirect.
1 Like
When I look at Stan Reference Manual page I don’t see any indication that it’s old. The Overview page says version 2.18 but doesn’t tell how recent that is or where to find the other versions. Shouldn’t the old docs link to the latest version?
1 Like
yes, that is the current situation, working on it - https://github.com/stan-dev/docs/issues/106
we can do this - both things circled in red redirect to latest - suggestions?
2 Likes
perhaps it’s a third order detail, but a distinct URL for ‘latest’ would lose having the version in the URL. by contrast, in Boost, clicking on the “take me to latest link” brings me to a versioned URL - e.g. - search “boost regex” shows 1_66 -
“Boost.Regex 5.1.3 - 1.66.0”
clicking on the “take me to latest” links takes me to:
“Boost.Regex 5.1.3 - 1.71.0”
1 Like
I moved the SEO discussion to Search engine optimization for the Stan docs
1 Like
I think that’s the point. If the version is in the latest URL, all Google search results are versioned.
For SEO, pointing to the latest (versioned or unversioned in the URL) would help. Having a single URL without the version for latest would be best for SEO to that link, I’d think.