Contenu de la première partie de la documentation #65

Closed linogaliana closed 3 years ago

In GitLab by @oliviermeslin on Jun 2, 2020, 14:21

Cette issue est une discussion sur le contenu et le plan de la première partie de la documentation. Je propose un premier plan, avec des idées en vrac. Je pense qu'on peut arriver à stabiliser le plan avant la réunion du 10 juin.

Une question structurante me semble être: documente-t-on à la fois l'usage de R en local et dans AUS? Ou seulement l'un des deux? Je pense qu'il faut couvrir les deux.

Tous commentaires et toutes modifications bienvenues.

Démarrage rapide de R à l'Insee
- où clique-t-on pour accéder à Rstudio?
- Où se trouve le Gitlab?
- Comment on se crée une librairie avec des droits en écriture?
- Comment on installe un package?
Comment (bien) utiliser R et Rstudio à l'Insee?
- Comment on se connecte à AUS;
- Comment on lance Rstudio.
- Comment on utilise les projets Rstudio.
Comment personnaliser sa configuration R et Rstudio sous AUS (ou en local)?
- Parler du fichier .Rprofile, et dire ce qui peut être configuré.
- D'autres idées?
Comment installer des packages?
- Comment on se crée une librairie avec des droits en écriture? (.libPaths() et autres);
- Expliquer qu'il y a des miroirs pour AUS;
- Expliquer comment installer un package (et aussi binary versus source).
Comment utiliser la gestion de version : GitLab et RStudio?
- Des bases de Git: Reprendre la partie 4.2 de la formation Travail Collaboratif sous R.
- Où mettre son dépôt local Git (en local et dans AUS)
- Utiliser Git avec l'interface Rstudio
Travailler avec le Gitlab interne
- Présentation du Gitlab interne
- Configurer son accès à Gitlab (SSH, Putty etc.)
- Comment travailler à plusieurs avec Gitlab? Reprendre la partie 4.4 de la formation Travail Collaboratif sous R.
Comment se former à R à l'Insee ? Le parcours de formation, by @mathias.andre

In GitLab by @pierre-lamarche on Jun 2, 2020, 19:50

Cela me paraît très bien comme plan @oliviermeslin. Un seul bémol pour moi, c'est la redondance du "Comment on se crée une librairie avec des droits en écriture". Je ne le mentionnerais pas dans le démarrage rapide, je pense que cela va plutôt dans l'escarcelle d'une utilisation avancée de R : l'objet c'est finalement d'expliquer la mécanique interne de R et d'expliquer comment et où le système installe les packages additionnels, alors que cela peut rester assez transparent du point de vue de l'utilisateur débutant. Pour le reste, j'adhère avec cette idée de graduer la difficulté au fil du plan.

Par ailleurs, je pense qu'il y a un sujet environnement qu'il faut aborder assez rapidement dans la section Démarrage rapide, mais qui doit revenir ensuite sur plusieurs sujets. Utiliser RStudio à l'Insee, ça peut être sous AUS, sous r.insee.fr (même si cette option est fortement putrescible), en local ou sous la plateforme Innovation. Dans ces différents cas, la façon dont on configure Git ou dont on gère la personnalisation du logiciel varie (typiquement on charge le user-settings sous la plateforme Innovation, quand les choix de personnalisation sont conservés en local ou sous AUS) ; et donc il va falloir trouver une façon pas trop rébarbative de présenter toutes ces différentes variations qui peuvent vraiment alourdir la présentation.

In GitLab by @sylvain.daubree on Jun 3, 2020, 05:01

ça me semble très bien également, d'accord avec Pierre sur la question environnement, est-ce que ça ne vaudrait pas le coup de rajouter un point "sur quel environnement faut-il que je parte ?" qui explique brièvement les avantages/inconvénients de R poste, R AUS, R.insee.fr et R innovation. Là il me semble qu'on mélange un peu les choses (avec le point gitlab qui vient très tôt à mon avis et qui demande quand même un peu de contexte). En gros je pense que je verrais bien ce point, et ensuite un chapitre dédié à chaque environnement qui explique comment il fonctionne. Quitte à écrire les choses en double (ou en triple) ça rendra je pense la lecture plus simple (le débutant ne va s'intéresser à mon avis qu'à un seul environnement à la fois)

In GitLab by @linogaliana on Jun 3, 2020, 07:11

Comment on se crée une librairie avec des droits en écriture? (.libPaths() et autres);

Je ne pense pas qu'il faille présenter ça. L'utilisation d'un .libPaths personnel n'est pas une solution très pérenne ni fiable ; c'est une rustine qu'on peut faire parfois, mais je ne suis pas sûr qu'il faille la présenter

Je pense en effet que présenter les différentes solutions possibles, leurs avantages respectifs ainsi que leurs limites est bien. Avec du code HTML, pour le bookdown html, on doit pouvoir avoir un petit élément flotant qui mentionne à quel environnement ce paragraphe fait référence (et pour LateX, un élément en marge ?)

In GitLab by @CTassart on Jun 3, 2020, 08:40

je trouve également ce plan cohérent.

Dans la partie Comment bien utiliser RStudio à l'Insee, ne serait-il pas intéressant de présenter un peu plus RStudio (les principaux menus (Tools/Global Options), les différentes fenêtres (console, environnement)...) ?
Je pense également qu'il serait bien de présenter les différents environnements dans lesquels on peut faire du R (AUS, Poste, r.inseee.fr, PFI) :
- en expliquant les principaux avantages (et inconvénients) de chaque environnement,
- mentionnant les inconvénients à utiliser plusieurs environnements (passer d'une version poste récente à une version AUS qui l'est moins par exemple). Ensuite, il faut peut-être garder une version de référence qui serait, à mon sens, la version AUS car elle pourrait être la principale porte d'entrée à l'apprentissage de R. Après, si on sait faire du R sur AUS on saura le faire sur poste, la PFI me semble s'adresser à un public plus aguerri et r.insee.fr ...(presque) RIP, non ?
Je suis plutôt favorable à la présentation du .libpath perso mais je ne mesure peut-être pas bien les inconvénients (l'effet rustine dont parle @linogaliana ) et les façons plus propres de faire sans .libpath perso.
Je pense aussi (comme @sylvain.daubree ) qu'on aborde gitlab un peu tôt. On est déjà un peu dans des pratiques (versionning, collaboratif...) plus avancées qui ne concernent pas encore tous les débutants mais le sujet est tellement intéressant qu'il mérite bien sa partie.
binary vs source : oui oui oui !
Le parcours de formation : encore oui oui oui. c'est devenu un peu nébuleux entre les anciennes formations et les nouvelles.

In GitLab by @clairelegroux on Jun 3, 2020, 17:18

Je rejoins l'avis de @sylvain.daubree Git me parait abordé trop tôt un premier "chapitre" sur les environnements possibles serait bienvenue, c'est effectivement la première question qu'on se pose : "euh je passe par quoi ?"

pour le poste, gardez à l'esprit qu'on a supprimé l'installation de la version 3.3. Et qu'on va trés rapidement proposer un paquet 3.6 poste (dans la mesure du possible, au moment de la 1ère sortie d'AUS V3) Que dans ce contexte les versions AUS seront

R 'dev' 4.0 (et chaque correctif qui sort dans l'année à venir (puis en 'stable' en avril 2021 et en old d'avril 2022 à 2023).
R 'stable' 3.6 jusqu'en avril 2021 (qui passera en old ensuite jusque avril 2022
R 'old' 3.4 et 3.3 jusqu'en avril 2021 (qui ne seront plus proposés ensuite)

ce schéma de version est commun à tous les env de prod (PFI exclue donc, mais je crois que là vous avez plus de liberté justement !)

entre AUS V3 et le poste, on sera dans les 2 cas en Windows. Si on est sur la même version, la config perso n'est elle pas transposable ?

pour r.insee.fr il y a "normalement" jusque fin 2021, on n'est pas encore en RIP

y-a-t-il un préambule / avertissement quelque part, qui indique qu'on fait le choix de présenter essentiellement l'usage via R Studio comme première approche ? Car sinon, quels critères de choix console ou IDE ?

In GitLab by @oliviermeslin on Jun 3, 2020, 18:49

Merci à tous pour ces retours détaillés. Je regarde ça demain, je vous réponds et je vous propose un plan mis à jour.

In GitLab by @oliviermeslin on Jun 4, 2020, 07:41

Je crée une MR avec une proposition de plan mise à jour

In GitLab by @oliviermeslin on Jun 4, 2020, 08:18

Dans la partie Comment bien utiliser RStudio à l'Insee, ne serait-il pas intéressant de présenter un peu plus RStudio (les principaux menus (Tools/Global Options), les différentes fenêtres (console, environnement)...) ?

OK. J'ajoute

Je pense également qu'il serait bien de présenter les différents environnements dans lesquels on peut faire du R (AUS, Poste, r.inseee.fr, PFI) :

C'est fait, ça rejoint les remarques de @pierre-lamarche et @sylvain.daubree.

Je pense aussi (comme @sylvain.daubree ) qu'on aborde gitlab un peu tôt. On est déjà un peu dans des pratiques (versionning, collaboratif...) plus avancées qui ne concernent pas encore tous les débutants mais le sujet est tellement intéressant qu'il mérite bien sa partie.

Je vais déplacer ça plus bas.

binary vs source : oui oui oui !

Je l'ai mentionné car je sais que c'est important mais je n'y connais rien. Si tu connais le sujet, tu es le bienvenu pour l'expliquer.

Le parcours de formation : encore oui oui oui. c'est devenu un peu nébuleux entre les anciennes formations et les nouvelles.

Ca c'est sûr. Il me semble vraisemblable que l'arrivée d'UtilitR va déclencher une réorganisation des contenus de formation. Cette partie risque d'être difficile à rédiger à court terme.

In GitLab by @oliviermeslin on Jun 4, 2020, 08:23

est-ce que ça ne vaudrait pas le coup de rajouter un point "sur quel environnement faut-il que je parte ?"

C'est fait

En gros je pense que je verrais bien ce point, et ensuite un chapitre dédié à chaque environnement qui explique comment il fonctionne. Quitte à écrire les choses en double (ou en triple) ça rendra je pense la lecture plus simple (le débutant ne va s'intéresser à mon avis qu'à un seul environnement à la fois)

Très bonne idée, même si ça risque d'être long. Je pense qu'on peut essayer de faire qu'un maximum de sections soient valables pour tous les environnements (installations de packages, utilisation des projets Rstudio...). Je fais une proposition en ce sens.

In GitLab by @oliviermeslin on Jun 4, 2020, 08:23

Un seul bémol pour moi, c'est la redondance du "Comment on se crée une librairie avec des droits en écriture". Je ne le mentionnerais pas dans le démarrage rapide,

OK

je pense qu'il y a un sujet environnement qu'il faut aborder assez rapidement dans la section Démarrage rapide, mais qui doit revenir ensuite sur plusieurs sujets.

OK. J'ai fait une proposition, mais ce n'est pas dans la partie démarrage rapide, mais dans la première sous-section qui suit le démarrage rapide.

il va falloir trouver une façon pas trop rébarbative de présenter toutes ces différentes variations qui peuvent vraiment alourdir la présentation.

Effectivement ça va pas être simple.

In GitLab by @oliviermeslin on Jun 4, 2020, 08:27

entre AUS V3 et le poste, on sera dans les 2 cas en Windows. Si on est sur la même version, la config perso n'est elle pas transposable ?

Je ne sais pas ce qu'on peut faire avec les fichiers de config, je laisse les collègues répondre.

y-a-t-il un préambule / avertissement quelque part, qui indique qu'on fait le choix de présenter essentiellement l'usage via R Studio comme première approche ? Car sinon, quels critères de choix console ou IDE ?

Oui, on dit dans le Readme.md qu'on recommande l'usage de R avec Rstudio. Il me semble le choix console versus IDE n'en est pas vraiment un pour la grande majorité des agents amenés à utiliser R en self. Par exemple, je suis incapable d'utiliser R en ligne de commande, et pour moi Rstudio est une évidence.

In GitLab by @oliviermeslin on Jun 4, 2020, 08:31

@pierre-lamarche, @sylvain.daubree, @linogaliana, @CTassart, @clairelegroux: J'ai créé la MR !51 en intégrant vos commentaires.

Pouvez-vous relire une nouvelle fois? Vous pouvez modifier directement par des commits.

In GitLab by @linogaliana on Jun 4, 2020, 08:42

@clairelegroux je te réponds:

entre AUS V3 et le poste, on sera dans les 2 cas en Windows. Si on est sur la même version, la config perso n'est elle pas transposable ?

Il peut exister quelques différences. L'exemple immédiat qui me vient en tête est le proxy: inutile sous AUS (pas d'accès internet), indispensable sur poste local (via .Renviron)

In GitLab by @linogaliana on Jun 4, 2020, 08:45

En gros je pense que je verrais bien ce point, et ensuite un chapitre dédié à chaque environnement qui explique comment il fonctionne. Quitte à écrire les choses en double (ou en triple) ça rendra je pense la lecture plus simple (le débutant ne va s'intéresser à mon avis qu'à un seul environnement à la fois)

J'avais à l'esprit, dans mes rêves les plus fous, une manière de faire cela via des onglets dans le livre html et via une annotation dans la marge qui rappelle sur quel environnement ce paragraphe est valable. C'est un peu plus lourd dans la conception du livre mais ça peut être intéressant (j'ai précisé dans mes rêves les plus fous)

In GitLab by @oliviermeslin on Jun 4, 2020, 10:36

Ca peut être une bonne idée. Ou on peut réfléchir à une façon de distinguer visuellement les recommandations en fonction de l'environnement où elles sont valables (un truc similaire aux boxes colorées par exemple). Mais à mon sens il faut que cela soit réduit au minimum, sinon la doc risque de devenir illisible.

In GitLab by @linogaliana on Jun 4, 2020, 11:37

Oui c'est pour les éléments spécifiques mais qui méritent néanmoins approfondissement, par exemple la création des clés SSH (spécifique au poste local, peut-être à AUS aussi on en apprendra plus bientôt)

In GitLab by @oliviermeslin on Jun 9, 2020, 09:12

Le plan a été fusionné, je ferme l'issue

In GitLab by @oliviermeslin on Jun 9, 2020, 09:12

closed

In GitLab by @clairelegroux on Jun 9, 2020, 18:33

ok pour la différence local / AUS @oliviermeslin pour la question IDE/ligne de commande, je pense notamment à @AntoineDreyer et Jean Luc, qui pour des raisons peut être différentes apportent des arguments à l'usage de la ligne de commande. Celui que j'ai retenu c'est la performance.

In GitLab by @oliviermeslin on Jun 9, 2020, 18:52

Je ne doute pas que la ligne de commande présente beaucoup d'avantages. Toutefois, il me semble préférable de rester sur Rstudio, pour proposer un environnement un peu presse-boutons qui sera vaguement familier pour les néophytes complets qui ne connaissent que SAS.

A vrai dire, les utilisateurs qui sont en mesure d'utiliser R en ligne de commande n'auront pas autant besoin de la première partie d'UtilitR que les grands débutants en R qui arrivent de SAS.

InseeFrLab / utilitR

Contenu de la première partie de la documentation #65