Utiliser les directives du dépôt GitHub pour améliorer l'expérience des développeurs

Chez Nexmo, nous aimons partager du code avec nos communautés de développeurs. Habituellement, cela signifie publier dans un repo git sur GitHub afin que tout développeur souhaitant utiliser le code puisse le faire.

Nous nous sommes cependant rendu compte que nous avons maintenant environ 300 dépôts répartis entre plusieurs organisations GitHub différentes, et qu'il peut être difficile de trouver ce dont vous avez besoin et de comprendre comment utiliser chaque projet, à moins qu'il n'y ait de bonnes instructions.

Afin d'améliorer l'expérience des développeurs, nous avons créé (puis partagé publiquement) nos normes de référentiel.

Des normes appropriées pour les différents types de repo

Nous avons identifié trois types de projets que nous publions souvent et avons adapté nos lignes directrices à chacun d'entre eux.

SDK

Nos SDK sont facilement les dépôts les plus utilisés et nous en sommes fiers ! Les utilisateurs, quel que soit leur niveau d'expérience, doivent pouvoir accéder à ces projets et comprendre comment ils peuvent les utiliser dans leurs propres projets pour effectuer des tâches spécifiques à Nexmo. Nous avons apporté un soin particulier aux instructions d'installation et à la clarté de la licence afin que notre communauté puisse utiliser nos SDK en toute confiance.

Applications de démonstration

Nous publions de nombreuses applications de démonstration. Il s'agit d'applications autonomes destinées à démontrer une fonctionnalité particulière de Nexmo, et nous les mettons à la disposition des autres pour qu'ils les copient et les utilisent. Avoir une déclaration claire des fonctionnalités et de l'objectif du projet est vraiment important dans un référentiel comme celui-ci. Nous avons également travaillé sur les licences et sur l'inclusion d'installations docker ou de boutons "click to deploy" pour permettre aux utilisateurs d'essayer ce que nous avons fait pour eux.

Le danger des normes, quelles qu'elles soient, est que les règles deviennent incontrôlables ! Beaucoup de nos dépôts ne sont que la version publique d'une application autonome unique qui a été créée pour illustrer un tutoriel, un article de blog ou une vidéo afin de montrer aux développeurs quelque chose en particulier.

Si nous ne publiions que ceux qui sont parfaitement décrits avec des caractéristiques de déployabilité et des instructions d'utilisation détaillées, il y aurait beaucoup moins de dépôts sur notre compte GitHub !

En fait, la seule règle est que le dépôt doit avoir un lien vers l'objet qu'il soutient. README qui comporte un lien vers l'objet qu'il soutient.

Ne me faites pas réfléchir

Nous avons créé les standards de référentiel dans une tentative de capturer une liste de contrôle partagée des choses que nous pensons être importantes lorsque nous publions un référentiel. Tout le monde avait ses propres idées, mais en tant qu'équipe composée principalement d'ingénieurs, cela ne se traduisait pas toujours par l'excellence lorsqu'il s'agissait de choses qui ne sont pas du code.

En créant des listes de contrôle et des modèles pour les choses les plus courantes, nous avons transformé "faire ce qu'il faut" en "faire ce qu'il faut". "Faire la chose facile"et amélioré l'expérience des développeurs qui trouvent nos projets sur GitHub.

Nous avons commencé par un modèle README de base pour donner une structure simple et nous rappeler de faire un lien vers la documentation du développeur et d'indiquer aux utilisateurs comment nous contacter s'ils en ont besoin. C'est basique, mais c'est beaucoup mieux que rien.

Chaque dépôt a besoin d'une licence, et nous choisissons par défaut MIT. Le fait de disposer de lignes directrices, y compris d'une liste de contrôle, nous rappelle que c'est ce que nous voulons faire.

Nous avons également un fichier de base CONTRIBUTING il est incomplet parce qu'il est difficile de le généraliser, mais il nous donne un point de départ et laisse un peu moins de travail aux créateurs de dépôts lorsqu'ils ont du code à partager.

L'expérience du développeur est une question de détails

Les détails ici sont mineurs, et il y a beaucoup plus de choses dans les lignes directrices complètes - mais les détails ont de l'importance. Les développeurs peuvent arriver sur vos dépôts GitHub, peut-être sans savoir ce qu'ils ont trouvé ou où aller ensuite. Les aider à s'orienter sur ce qu'ils sont, ce que ce dépôt représente, et où ils peuvent aller ensuite, sont tous des ingrédients importants pour une meilleure expérience du développeur.