Promoting developer version documentation in search engines and user forum posts

[Jean-Paul Pelteret]

Dear all,

When I answer posts on the forum I try my best to add links to relevant portions of the documentation.

I tend to choose (when I remember to do so) those from the developer page because I anticipate that these links would exist in perpetuity as we move to version 9 and beyond.

As sometimes its easier to search for a key phrase than a specific namespace/class/function, I preferentially use Google as opposed to the search bar in the Doxygen docs.

These searches typically bring up a mish-mash of older documentation and that from the developer version.

For example, searching for the GridTools::find_active_cell_around_point function (not the most robust construction of a query, but probably a typical one) returns links to v8.4.1 and older, and there's not even a link on the front page to the latest docs!

This leads me to wonder whether would it be useful (or even possible) to promote the developer version of the documentation in search engine results in preference to the older versions?

I think that this might be rewarding to the average user because then they'd get more exposure to the latest documentation (with all its enhancements) and to the newest functionality in deal.II.

Best regards,

J-P

Addendum:

In writing this post, I have just realised that some of the classes/functions that I link to may be deprecated and removed in time.

So perhaps I should be linking to the most recent stable version's documentation and (if possible) it's results should be returned preferentially by search engines.

Does anyone else have any thoughts on what the best practise for this is?

[Tobi Young]

> As sometimes its easier to search for a key phrase than a specific namespace/class/function, I preferentially use Google as opposed to the search bar in the Doxygen docs.

I still use grep locally for this, although I also use the doxygen search tool too.

> This leads me to wonder whether would it be useful (or even possible) to promote the developer version of the documentation in search engine results in preference to the older versions?

I don't know if it is useful, but it is an interesting academic question, that I am not interested in pursuing. Several  law suits have been processed involving entities trying to bias search engines in the way you suggest. (Polite warning!)

It seems, that you are restricting yourself to Google as a search engine. In that case, I would be tempted to ask the Google corporation how their search engine works.

Going back to the problem as stated In the case of depreceated or removed functions, I would choose to believe, that users are smart enough to figure out when they are looking at older docs. :-)

Does it suffice to observe that changing the deal.ii version 'x.x.x' to 'developer' in the hyper link almost always solves the problem you want to adress?

Best,
   Toby

[Bruno Turcksin]

Jean-Paul,

2016-12-01 17:56 GMT-05:00 Jean-Paul Pelteret <jppel...@gmail.com>:
> When I answer posts on the forum I try my best to add links to relevant
> portions of the documentation.
> I tend to choose (when I remember to do so) those from the developer page
> because I anticipate that these links would exist in perpetuity as we move
> to version 9 and beyond.

I actually try to do the opposite and not use the developer page :-)
Instead, I try to use the documentation of the latest release because
I assume that most people use the release version instead of the
development version. Sometimes the interface is slightly different or
the function does not exist in the latest release.

Best,

Bruno

[Jean-Paul Pelteret]

Hi Toby,

I still use grep locally for this, although I also use the doxygen search tool too.

Thats a good idea, if you know exactly what phrase you're looking for. Sometimes I can't think of the correct term and need to paraphrase and thats why a search engine is more useful for this purpose.

Several  law suits have been processed involving entities trying to bias search engines in the way you suggest. (Polite warning!)

This is not in relation to promoting the deal.II documentation above other results when searching for a term like "FEM". It more about the fact that our multiple versions of online documentation are, in effect, competing with one another! But I get it - this may fall foul of some rules regarding SEO unless using a mechanism like robots.txt (but I really haven't a clue as to what how websites work).

 

It seems, that you are restricting yourself to Google as a search engine.

I actually don't use the big G as my default search engine, but I'm sure that many people do. In any case, duckduckgo doesn't return as good results when looking through the documentation as Google does.

 

In that case, I would be tempted to ask the Google corporation how their search engine works.

Funny :-)

 

Going back to the problem as stated In the case of depreceated or removed functions, I would choose to believe, that users are smart enough to figure out when they are looking at older docs. :-)

 Unless the links are dead?

 

Does it suffice to observe that changing the deal.ii version 'x.x.x' to 'developer' in the hyper link almost always solves the problem you want to adress?

Thanks, I do know about this and end up doing it when constructing many of the posts (unless I forget...). Having to regularly perform this step is what motivated me to ask this question in the first place!

Best,

J-P 

[Jean-Paul Pelteret]

Hi Bruno,

That makes sense, and is another tick for the "use the latest release" column :-)

Thanks,

J-P

[Wolfgang Bangerth]

On 12/01/2016 03:56 PM, Jean-Paul Pelteret wrote:
> This leads me to wonder whether would it be useful (or even possible) to
> promote the developer version of the documentation in search engine results in
> preference to the older versions?

I think that's a valid question. The way I would probably do that is to
de-emphasize the items that are in the older versions. For example, we could
just prohibit robots from indexing the old directories. They're still
available for those who go through the website, for example.

Prohibiting indexing requires that we change all html files of older versions
(using one of the meta tags at the top of an HTML file), or placing a
robots.txt file into these directories. That requires access to the web
server, though.

Best
W.

--
------------------------------------------------------------------------
Wolfgang Bangerth email: bang...@colostate.edu
www: http://www.math.colostate.edu/~bangerth/

[Denis Davydov]

>
> Prohibiting indexing requires that we change all html files of older versions
> (using one of the meta tags at the top of an HTML file), or placing a
> robots.txt file into these directories. That requires access to the web

I think you can forbid indexing robots from going into directories trees In a single the root robots.txt.

Regards,
Denis