Rédacteur technique / ingénieur documentation — tâches, une par une

Rédiger la référence

C'est la tâche d'écriture la plus exposée de ce site, parce que la source de vérité est lisible par machine et le format de sortie est fixe. Produire un tableau de paramètres à partir d'une signature était déjà partiellement automatisé par les générateurs de documentation bien avant les modèles ; ce que les modèles ont ajouté est une prose qui se lit comme si une personne l'avait écrite, ce qui a retiré la dernière raison d'avoir une personne pour l'écrire.

Une référence générée est une référence que personne n'a lue avant publication, et le mode de défaillance n'est pas l'erreur mais la vraisemblance : une documentation qui décrit ce que le code déclare plutôt que ce qu'il fait. Cet écart n'est trouvé que par quelqu'un qui se sert de la chose, c'est-à-dire la tâche ci-dessous — automatiser celle-ci élève donc la valeur de celle-là plutôt qu'elle ne retire le métier.

Se servir vraiment de ce que vous documentez

L'entrée de cette tâche n'existe dans aucun dépôt : c'est l'expérience d'être perdu à un endroit précis. Un modèle entraîné sur la base de code hérite du savoir de l'ingénieur, or c'est précisément ce savoir qui doit être absent pour que l'épreuve fonctionne — ici la valeur vient de ne pas savoir.

Cette tâche est l'argument le plus fort en faveur du métier et le plus faible dans une réunion budgétaire, parce que son résultat est une absence — des tickets de support qui n'ont pas eu lieu. Là où des équipes de documentation ont été réduites, c'est la tâche qui est partie la première, et rien dans la technologie n'était nécessaire pour cela.

Décider ce qui ne sera pas écrit

Une production bon marché fait de ceci la tâche la plus précieuse plutôt que la moins, parce que la contrainte a bougé : quand tout écrire est devenu possible, choisir est devenu tout le métier. Décider ce qu'on laisse de côté dépend de savoir quels utilisateurs existent et ce qu'ils essaient de faire, et cela n'est pas dans le code.

Être plus précieux n'est pas la même chose qu'être reconnu : la documentation se mesure d'ordinaire à la couverture, et la couverture est exactement l'indicateur qu'une production bon marché vide de sens. Une équipe jugée sur les pages publiées sera récompensée d'abandonner cette tâche au moment même où elle devient l'importante.

Obtenir la réponse d'un ingénieur

L'information nécessaire est par définition non documentée — si elle était écrite, cette tâche n'existerait pas. L'extraire est un acte social mené contre l'agenda de quelqu'un, et le savoir-faire consiste à savoir quelle question produit la vraie réponse plutôt que la réponse officielle.

Cette tâche est ce qui rend le métier difficile à exercer à distance, à temps partiel ou depuis la chaise d'un prestataire — c'est-à-dire exactement la direction vers laquelle la pression sur les coûts le pousse. La menace ici n'est pas l'automatisation, c'est que le poste soit restructuré en quelque chose qui ne peut plus contenir cette tâche, après quoi la documentation se dégrade pour des raisons que personne n'attribue correctement.