Réorganisation de la doc

[babastienne]

Proposition de réorganisation pour la documentation Geotrek

Retirer des sections obsolètes / anciennes

Afin d'alléger la documentation on pourrait retirer quelques éléments. Dans tous les cas ces éléments seront toujours consultable dans les anciennes versions de la documentation

• https://geotrek.readthedocs.io/en/2.111.0/install/maintenance.html#major-evolutions-from-version-2-33
• https://geotrek.readthedocs.io/en/2.111.0/install/upgrade.html#from-geotrek-admin-2-32
• https://geotrek.readthedocs.io/en/2.111.0/install/upgrade.html#from-geotrek-admin-2-69-0
• https://geotrek.readthedocs.io/en/2.111.0/install/synchronization.html#synchronization-with-a-distant-geotrek-rando-server > obsolète depuis suppression de sync_rando
• https://geotrek.readthedocs.io/en/2.111.0/install/import.html#sensitive-areas-import > Doublon avec https://geotrek.readthedocs.io/en/2.111.0/install/import.html#import-sensitive-areas ?

Modifications

• https://geotrek.readthedocs.io/en/2.111.0/install/upgrade.html#from-geotrek-admin-2-33

  • Renommer cette section en "Upgrade Geotrek-Admin"
  • La partie "If your current version is <= 2.40.1 you should run instead:" devrait être ajoutée sous forme de warning bloc

• Section Configuration > Translations : Ajouter une phrase pour dire qu'il est préférable dans le doute d'ajouter des langues au moment de l'installation quitte à ne pas les utiliser ensuite plutôt que d'en mettre moins et d'ensuite devoir galérer à en ajouter

• Réorganiser les sections :

  • Conserver la section "Installation & configuration" mais en créer une autre dédiée "Import data". Ensuite on séparer u peu les contenus pour avoir des pages plus courtes et plus digestes. On aura ainsi l'arborescence suivante :

Installation & Configuration
|  Installation
|   Upgrade
|   Configuration
|   Advanced configuration
|   Maintenance
|   Exploitation commands
|   Synchronization
Import data
|   Prerequisites for your data
|   Load MNT raster
|   Import paths
|   Import other datas from a file
|   Import from network
     |   Import data from touristic data systems (SIT)  : (et meme cette section pourrat être à nouveau split en plusieurs sections, car il y a dedans du générique et du spécifique)
     |   Import data from a remote Geotrek instance
     |   Import sensitive areas

• Dans Import data from touristic data systems (SIT) > Ajouter une sous-section Import data from Cirkwi en se basant sur ce commentaire : Flux Cirkwi : évolutions à venir #3947 (comment)
• https://geotrek.readthedocs.io/en/2.111.0/install/import.html#import-treks-from-apidae > Ajouter un exemple de code ?
• Agrégateur : ajouter une section dédiée avec un exemple de fichier de conf générique ?
• Tourinsoft : même si c'est spécifique et jamais la même chose, ajouter un exemple de code simple générique qui permettrait l'import ?

[camillemonchicourt]

Attention quand on renomme ou réorganise la documentation, les URL peuvent beaucoup changer.
Et on a des liens vers des sections de la doc à différents endroits.
Il est possible de définir des redirections dans la conf d'un projet depuis l'interface READTHEDOCS, mais à bien lister en anticiper.

[babastienne]

Oui mais la doc est versionnée justement pour éviter ce sujet : quand on envoi un lien vers une section c'est versionné donc normalement les gens qui ont un lien ne seront pas impactés

[camillemonchicourt]

Non, justement on renvoie vers /latest/ justement pour renvoyer sur une doc à jour, même si on clique sur le lien 6 mois plus tard.

[babastienne]

curl --head https://geotrek.readthedocs.io/

Retourne un 302 pour rediriger vers la dernière version de Geotrek

HTTP/2 302
date: Mon, 16 Dec 2024 16:09:19 GMT
content-type: text/html; charset=utf-8
content-length: 0
location: https://geotrek.readthedocs.io/en/2.111.0/
cf-ray: 8f2fefe869026ecf-CDG
cf-cache-status: HIT
age: 159
cache-control: max-age=1200
content-language: fr
strict-transport-security: max-age=31536000; includeSubDomains; preload
vary: Accept-Language, Cookie, Accept-Encoding
cdn-cache-control: public
cross-origin-opener-policy: same-origin
referrer-policy: no-referrer-when-downgrade
x-backend: web-ext-theme-i-0a898ad5561dcf468
x-content-type-options: nosniff
x-rtd-domain: geotrek.readthedocs.io
x-rtd-force-addons: true
x-rtd-project: geotrek
x-rtd-project-method: public_domain
x-rtd-redirect: system
x-rtd-version-method: path
x-served: Django-Proxito
set-cookie: _cfuvid=mKc6jTs1TbRNsKygLs5HWIP6lFAdoIgQD4SLRkPtu_4-1734365359457-0.0.1.1-604800000; path=/; domain=.readthedocs.io; HttpOnly; Secure; SameSite=None
server: cloudflare
alt-svc: h3=":443"; ma=86400

Donc non on ne renvoi pas vers latest. On redirige vers la version courante pour que les gens ensuite qui naviguent et veulent copier un lien puissent le faire et ensuite quand il collent le lien ils auront la même version de la doc qu'à l'époque.

[camillemonchicourt]

Je parle de liens externes vers des pages précises de la documentation :

• https://pro.cirkwi.com/importez-vos-donnees-geotrek-dans-cirkwi/
• Pages statiques - Affiner et préciser la mise en forme Geotrek-rando-v3#466

Et plein d'autres.

[babastienne]

@camillemonchicourt oui j'ai bien compris, mais justement, ces liens ne devraient pas être diffusés. L'objectif de rediriger l'utilisateur vers une version quand il va sur la doc c'est justement pour lui éviter de copier-coller un lien avec dedans "stable" ou "latest" ou "master" plutôt qu'une version.

Donc si demain quelqu'un diffuse un lien avec "stable" dedans plutôt qu'une version c'est que cette personne a volontairement modifié l'url avant de la diffuser, donc tant pis pour elle.

Peut-être que ça a été fait auparavant mais ce n'est plus le cas et c'est une mauvaise pratique justement parce que ça nous oblige à devoir gérer (éternellement ?) des rétrocompatibilité d'URL.
Donc plutôt que de devoir gérer toutes les rétrocompatibilités il faudrait plutôt lister les quelques pages qui ont des liens comme ça et mettre des redirection en place que pour ces liens.

[camillemonchicourt]

Je ne suis pas vraiment d'accord avec ça.
Par exemple Cirkwi a fait un article sur la passerelle Geotrek>Cirkwi.
C'est important que leur lien dans cet article renvoie vers "latest", car leur article est là depuis au moins 5 ans et ça serait gênant qu'ils renvoient vers la doc Geotrek-admin d'il y a 5 ans. Car si la doc a évolué entre temps, la plupart des personnes cliquant sur le lien ne s'en rendront pas compte et seront sur une documentation et des infos potentiellement obsolètes.

[marcantoinedupre]

J'appuie @babastienne sur le fait de se donner la possibilité de réorganiser facilement la doc sans devoir se soucier de maintenir une rétro-compatibilité de toutes les URLs avec latest ce qui peut être lourd. Et à mon avis c'est une bonne pratique d'utiliser une URL avec la version de Geotrek pour référencer une section de la doc sur un site externe car ça garantit le lien même si la section devient obsolète et est retirée dans les versions plus récentes.

Ce que je constate sur la plupart des documentations pour développeurs est qu'un bandeau très visible est présent en en-tête sur toutes les anciennes versions. Le bandeau peut inclure ou non un lien vers la dernière version. Par exemple : doc Angular ou Django.

À voir ce qu'on pourrait mettre en place facilement avec nos outils de documentation. Un simple bandeau avec éventuellement un lien général vers la dernière version devrait être faisable.

[babastienne]

Un simple bandeau avec éventuellement un lien général vers la dernière version devrait être faisable.

C'est déjà le cas dans la documentation de Geotrek actuellement.

[camillemonchicourt]

Ouais des développeurs sont familiers avec ces histoires de version, etc...
Pour une doc utilisateur ou administrateur de Geotrek-admin, je pense que le public est différent et que cela risque de poser des soucis.
Pour reprendre mon exemple, que Cirkwi renvoie vers une doc qui a plus de 5 ans et a potentiellement évolué depuis, je trouve ça bien dommage et même problématique.

Actuellement, il y a des redirections dans la conf Readthedocs du projet Geotrek-admin et je pense que c'est une bonne chose :