[Méta] Améliorer la documentation NGC

[Clemog]

Améliorer la documentation du modèle

Beaucoup de travail à été réalisé pour améliorer la lisibilité et la transparence du modèle de calcul ... mais ce travail a donné lieu à de nombreuses issues qu'il est temps de résoudre. Cette méta concerne, à la fois des points bloquants et des améliorations à apporter. Mais avant, un rapide état des lieux de l'actuel :

L'actuel

• Le modèle NGC est documenté directement via Publicodes, qui propose d'ailleurs dans la librairie un composant permettant de générer automatiquement la page /documentation/bilan à partir des règles de /data, affichant le calcul, les dépendances de chaque règle, les notes et descriptions du modèle.
• Une introduction à la documentation, "home" de la documentation qui permet de s'y retrouver un peu plus au départ
• Une page "Modèle" a été publiée pour expliquer rapidement ce qu'est le modèle et visualiser l'influence de certaines valeurs par défaut sur la valeur de départ
• D'autres "guides" qui pourraient s'apparenter à des docs sont présents sur le site mais peu référencés voir introuvables tels que les guides du mode groupe (#Meilleure visibilité des guides de l'animateur  #802)
• La FAQ est présente sur la page /contribuer ce qui n'est pas sa place, FAQ qui d'ailleurs pourrait être améliorée. On pourrait mieux gérer les ancres.
• Wiki côté site et modèle
• Releases

Les limites et améliorations possibles (à compléter bien sur)

• Il est difficile de se retrouver dans l'arborescence de la documentation avec le "menu" à gauche
• La documentation est générée à partir du calculs liées aux valeurs de sa propre simulation
• Auparavant le mécanisme référence était affiché dans la doc au même titre que que note et description ce qui ne semble plus être le cas <--- [Mael] je crois que si
• On ne peut pas rediriger vers une question précise de la FAQ

TO DO

Cette liste a été créée via les issues labellisées "documentation" (comme par hasard) du dépôt site. Certaines issues sont également labellisées côté modèle mais concerne des "manques" de complétude des notes / sources associées a certaines sujets. Je pense que certaines sont discutables, l'idée de l'issue est aussi d'en parler et de fermer celles qui sont obsolètes. Certains points sont éventuellement à convertir en issue, ce serait peut-être intéressant de faire un point dédié sur le sujet :)

Modèle

• document référencement de tous les facteurs d'émissions utilisés #215
• Services sociaux : améliorer les scripts de transformation des données SDES nosgestesclimat#1624
• - Consommation vélo = 0 impact ? et vélo électrique nosgestesclimat#914

Site

• Adapter l'affichage des quantités de CO2 (kg, tonnes, gr) #26 : pour afficher toujours le même nombre de chiffres significatifs en convertissant les valeurs dans les unités adéquats
• document référencement de tous les facteurs d'émissions utilisés #215 : pour permettre d'avoir une idée de tous les FE utilisés (on parle de FE pour toutes les règles qui permettent d'obtenir du CO2e et pas seulement les FE de la base carbone. Ce serait un travail intéressant lié en parti à l'issue citée précédemment
• Amélioration accès FAQ, documentation #346 : l'idée est ici de travailler sur le parcours utilisateur pour accéder à la doc ou plus généralement, à une info importante dans NGC (notamment la FAQ). Le pb vient du constat que beaucoup de questions utilisateurs trouvent déjà une réponse qque part dans la doc. Des améliorations notables ont été faite (page "home" de la doc, page "home" du site) mais on pourrait travailler davantage sur l'organisation des pages, l'indexation etc...
• Pouvoir changer les valeurs de la situation directement dans la doc #618 : les chiffres de la documentation sont ceux de "notre simulation". C'est une bonne chose : on pourrait alors modifier ses chiffres pour visualiser l'influence d'une question donnée sur le résultat. Or, on aimerait aussi pouvoir accéder aux chiffres "moyens" depuis google. Réflexions à prévoir ! (il me semble @laem que tu avais commencé qque chose ?)
• Améliorer la page /documentation pour expliquer le standard #484 : on peut dire que c'était la méta précédente, des éléments intéressants :)
• Idée de design de la page de démonstration du "modèle" #697 à terminer
• Réintroduire la notion de "cas types" ou personas dans la doc #1098
• Ajouter des graphes pour chaque sous-parties de la documentation (cf point 1 de Retours expérience utilisateur nosgestesclimat#893)

[laem]

J'ai commencé une PR sur publicodes pour améliorer la doc publicodes/publicodes#354