Swap <version> and <lang> in the manual url #51081

New Issue

Aaron Carlisle · 2017-03-29T17:51:53+02:00

Aaron Carlisle commented

2017-03-29 17:51:53 +02:00

Who

https://docs.blender.org/manual/en/dev/

What

This task is to discuss switching from having the language first to having the version first in the url.

Why

The reason why we should change this is it would be much more logical and streamline.
Languages are version specific, for example, one version may add a language or remove move them.

Because the are language specific the current set up makes it very difficult for us to upload new releases.
See the below directory layout for the current approach then see the one following.

Manual
  - en
      - 2.77
      - 2.78
  - fr
      - 2.77
      - 2.78
  - pt
      - 2.77
      - 2.78
  - ru
      - 2.77
      - 2.78
  - zn.tw
      - 2.78
  - ect...
      - 2.77
      - 2.78

Manual
  -2.78
       - en
       - fr
       - pt
       - ru
       - ect... 
  -2.79
       - en
       - fr
       - pt
       - ru
       - zn.tw (new lang)
       - ect...
  -ect...

While we can make it work with the first version it would make things much more difficult.
With the later, all I have to do is make one 2.79 folder and give it someone to upload to the server
However, with the other, I have to give someone a 2.79 folder for each language.
This purposed solution will also make our JSON and js files in D2544 much easier to maintain.

When

This will need to be done before we move forward with versioning the manual (D2544, #49262)

How

@Sergey will have to edit some apache stuff on the server.

Who ### https://docs.blender.org/manual/en/dev/ What **** This task is to discuss switching from having the language first to having the version first in the url. Why ### The reason why we should change this is it would be much more logical and streamline. Languages are version specific, for example, one version may add a language or remove move them. Because the are language specific the current set up makes it very difficult for us to upload new releases. See the below directory layout for the current approach then see the one following. ``` Manual - en - 2.77 - 2.78 - fr - 2.77 - 2.78 - pt - 2.77 - 2.78 - ru - 2.77 - 2.78 - zn.tw - 2.78 - ect... - 2.77 - 2.78 ``` ``` Manual -2.78 - en - fr - pt - ru - ect... -2.79 - en - fr - pt - ru - zn.tw (new lang) - ect... -ect... ``` While we can make it work with the first version it would make things much more difficult. With the later, all I have to do is make one 2.79 folder and give it someone to upload to the server However, with the other, I have to give someone a 2.79 folder for each language. This purposed solution will also make our JSON and js files in [D2544](https://archive.blender.org/developer/D2544) much easier to maintain. When **** This will need to be done before we move forward with versioning the manual ([D2544](https://archive.blender.org/developer/D2544), #49262) How ### @Sergey will have to edit some apache stuff on the server.

Aaron Carlisle commented

2017-03-29 17:51:53 +02:00

Changed status to: 'Open'

Aaron Carlisle commented

2017-03-29 17:51:53 +02:00

Added subscribers: @Sergey, @Blendify, @fsiddi, @Tobias

Sergey Sharybin commented

2017-03-29 19:14:03 +02:00

Ok, as i see now dev refers to a version, not to a developer's manual (obviously).

Points to consider here goes as following.

The existing layout was agreed on, spent time on and used for quite some time now. There are shared links everywhere in the internets now, so changing layout will wither break links (which is totally undesirable) or will force us to have bunch of redirect rules (which are PITA to maintain and which can always break in the future as well). If we REALLY want to change this, it's not just a web server configuration, but also the manual builder machine and scripts which needs update and troubleshoot.

All this is either time consuming or useless for users of the manual.

Now answering some raised points.

Languages are version specific, for example, one version may add a language or remove move them.

I do not see how this is an issue with the current directory layout. You can have some nice 404 page for missing versions. It's not like changing directory layout magically solves the issue.

Because the are language specific the current set up makes it very difficult for us to upload new releases.

Do not see an issue here either. We already have script which deploys latest version of manual. It is trivial to use it to deploy any version of any language. It is not like building will ever support batched upload anyway.

With the later, all I have to do is make one 2.79 folder and give it someone to upload to the server. However, with the other, I have to give someone a 2.79 folder for each language.

I do not see a point here. In theory, you can just copy dev to {BLENDER_VERSION} at a release file on server. Even with current layout it is doable with simple oneliner.

Alternatively, you run builder scrit with a given version on all languages and they will deploy manual for a specified language. It's not like new language will appear for a release and not for the latest version.

This purposed solution will also make our JSON and js files in D2544 much easier to maintain.

I do not see how this is related. It is questionable which JSON format is easier to maintain and even if the "swapped" one is easier you can always transpose the language/version order at a runtime.

All in all, i would really suggest sticking to the current layout unless there are unsolvable issues. If there are unsolvable issues please mention them explicitly and not just vague "makes things difficult".

Ok, as i see now `dev` refers to a version, not to a developer's manual (obviously). Points to consider here goes as following. The existing layout was agreed on, spent time on and used for quite some time now. There are shared links everywhere in the internets now, so changing layout will wither break links (which is totally undesirable) or will force us to have bunch of redirect rules (which are PITA to maintain and which can always break in the future as well). If we REALLY want to change this, it's not just a web server configuration, but also the manual builder machine and scripts which needs update and troubleshoot. All this is either time consuming or useless for users of the manual. Now answering some raised points. > Languages are version specific, for example, one version may add a language or remove move them. I do not see how this is an issue with the current directory layout. You can have some nice 404 page for missing versions. It's not like changing directory layout magically solves the issue. > Because the are language specific the current set up makes it very difficult for us to upload new releases. Do not see an issue here either. We already have script which deploys latest version of manual. It is trivial to use it to deploy any version of any language. It is not like building will ever support batched upload anyway. > With the later, all I have to do is make one 2.79 folder and give it someone to upload to the server. However, with the other, I have to give someone a 2.79 folder for each language. I do not see a point here. In theory, you can just copy `dev` to `{BLENDER_VERSION}` at a release file on server. Even with current layout it is doable with simple oneliner. Alternatively, you run builder scrit with a given version on all languages and they will deploy manual for a specified language. It's not like new language will appear for a release and not for the latest version. > This purposed solution will also make our JSON and js files in [D2544](https://archive.blender.org/developer/D2544) much easier to maintain. I do not see how this is related. It is questionable which JSON format is easier to maintain and even if the "swapped" one is easier you can always transpose the language/version order at a runtime. ---- All in all, i would really suggest sticking to the current layout unless there are unsolvable issues. If there are unsolvable issues please mention them explicitly and not just vague "makes things difficult".

Aaron Carlisle commented

2017-03-29 19:20:27 +02:00

Added subscriber: @ideasman42

Aaron Carlisle commented

2017-03-31 22:50:14 +02:00

@Tobias agrees that it should be swapped.

John Roper commented

2017-03-31 22:53:03 +02:00

Added subscriber: @JohnRoper

John Roper commented

2017-03-31 22:53:03 +02:00

I agree. I believe that usability trumps in this case.

Tobias Heinke commented

2017-04-01 12:58:35 +02:00

I changed my mind: Also language first is valid, because the language is common/static between the version. From this point of view it doesn't matter if xy is only offered since 2.78. And yes it makes no difference for the version switch (D 2544).
So if there are no benefits it would be better to use to the standard.

I changed my mind: Also language first is valid, because the language is common/static between the version. From this point of view it doesn't matter if xy is only offered since 2.78. And yes it makes no difference for the version switch (D 2544). So if there are no benefits it would be better to use to the standard.

Aaron Carlisle commented

2017-04-11 05:50:29 +02:00

Changed status from 'Open' to: 'Archived'

Aaron Carlisle closed this issue

2017-04-11 05:50:29 +02:00

Aaron Carlisle self-assigned this 2017-04-11 05:50:29 +02:00

Aaron Carlisle commented

2017-04-11 05:50:29 +02:00

Talked on IRC a bit more. While swapping them would give nice benefits we decided to go with the standard.

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Swap <version> and <lang> in the manual url #51081