Rédaction

Une année d'apprentissage d'une langue avec Duolingo

Je devrais être bilingue. J’ai grandi dans un pays où la langue indigène n’est pas l’anglais. Mais, comme cela avait suscité 741 ans que le Pays de Galles a été annexé par l’Angleterre, ce n’est pas que la langue galloise soit en déclin qui est surprenant, c’est qu’il reste encore des locuteurs natifs. J’ai suivi un an de cours avant de quitter la capitale pour un comté frontalier. Je me souviens comment compter jusqu’à cinq, et c’est à peu près tout. Au lieu de cela, on m’a enseigné le français, mal. Au fil des ans, j’ai essayé diverses approches pour secouer mon monolinguisme, sans grand résultat, jusqu’à ce que je revienne à Duolingo.

Profil: Chris Horrie

J’ai suivi ma formation en journalisme au London College of Printing au siècle dernier, à l’époque où les journaux existaient encore. Il s’agissait essentiellement d’un cours de formation de 13 semaines NCTJ (sans accréditation de la NCTJ) et d’un cours accéléré de publication assistée par ordinateur, ajouté à un diplôme d’arts libéraux. Cela m’a été très utile. La partie “arts libéraux” a été assurée par le Yorkshireien Roger Fieldsend et l’anarchiste philosophique Barney Summers. Cela a permis de combler les lacunes de ceux qui, comme moi, n’ont pas reçu d’éducation classique. Kathy Hilton m’a appris presque tout ce que je sais sur la typographie et la mise en page (et suffisamment sur QuarkXpress pour que j’obtienne un emploi d’été en tant que rédacteur au cours de ma deuxième année). Le technicien du laboratoire informatique m’a appris à utiliser Photoshop (avant qu’il n’y ait des calques) et le fonctionnement interne du Macintosh d’Apple. Le professeur de journalisme était Antony Delano, avec qui je suis resté en contact pendant un certain temps. Mon directeur de mémoire était Paul Charman (qui s’est brouillé avec son ami Mark Knopfler après avoir écrit sur lui pour Time Out. Le directeur du cours était Chris Horrie. J’étais absent (par manque de fonds) lorsqu’ils ont attribué les postes pour le projet de journal étudiant. On m’a confié le poste de rédacteur en chef. Cela signifiait que je ne pourrais pas écrire pour le journal. J’ai été contrarié lorsque mes mises en page avant-gardistes ont été rejetées, et j’ai décidé de trouver un moyen de faire publier quelque chose. J’aurais peut-être dû tirer les leçons de l’erreur de Charm, mais j’ai fini par écrire un portrait de Chirs. Il comporte quelques inexactitudes mineures, mais je le présente ici tel qu’il a été publié il y a une trentaine d’années.

Création d'un guide de style pour l'API

On m’a récemment demandé quelles étaient mes ressources préférées et mes meilleures pratiques pour rédiger des documents clairs et structurés sur les API. J’ai développé mon propre style pour la rédaction des documents d’API, mais jusqu’à présent je ne l’ai pas publié. Bien que j’aie principalement travaillé avec des API REST, ces conseils s’appliquent également à GraphQL et à toute autre API. Mais avant d’aborder le style d’écriture, l’exigence la plus importante pour de bonnes documentations d’API est une bonne API. Si vous utilisez REST, validez-la avec Stoplight. Si les points de terminaison ne sont pas cohérents dans la manière dont ils gèrent les paramètres communs, il n’y a aucun moyen de contourner le problème. Cela semble être un problème plus important avec REST et peut expliquer l’abandon de REST au profit de GraphQL. La prochaine chose dont vous avez besoin est une documentation statique et consultable. N’attendez pas de vos utilisateurs GraphQL qu’ils trouvent les informations dont ils ont besoin en parcourant votre schéma dans Apollo. N’attendez pas de vos utilisateurs REST qu’ils fassent défiler le bas de la page de l’interface Swagger pour savoir comment formater les données pour un point de terminaison donné. Si vous avez besoin d’une solution sans budget, Redocly CLI et Magidoc sont de bons points de départ pour REST et GraphQL respectivement. À moins que vous n’utilisiez un hébergement AWS (qui n’est pas compatible avec les URL propres de Magidoc). Et ne pensez pas que vous avez terminé lorsque vous avez publié votre schéma. Les développeurs ont besoin de flux de travail, d’exemples de code et d’informations de référence pour comprendre comment ils sont censés utiliser votre API. Idéalement, ces informations devraient figurer sur un portail public destiné aux développeurs. Vos concurrents ne pourront pas cloner votre produit en examinant votre API. Et même s’ils commencent à ajouter des fonctionnalités basées sur votre API, vous aurez toujours plusieurs longueurs d’avance.

Les systèmes hybrides de gestion des documents revisités

En janvier de l’année dernière, j’étais candidat à un poste de responsable de la documentation et je devais trouver une solution pour répondre aux besoins des rédacteurs et des développeurs-contributeurs. Ma solution ressemblait à peu près à ceci:

Byte High, No Limit devient mensuel

J’ai décidé rétroactivement de ramener le blog Byte High, No Limit à une cadence régulière. Pendant les deux premières années et demie de son existence, j’ai publié un nouvel article tous les jeudis. Mais d’autres pressions sur mon emploi du temps ont fait que ce rythme est devenu insoutenable. L’année dernière, après avoir mis fin à la publication hebdomadaire au milieu de l’année, j’ai publié quatre articles supplémentaires pour un total de 30. Je pense qu’un article par mois est probablement faisable, notamment parce que c’est la cadence à laquelle de nombreux YouTubers qui avaient l’habitude de publier de nouvelles vidéos chaque semaine sont maintenant passés. Et les vidéos de qualité demandent beaucoup plus de travail que cela. Cette année, les nouveaux articles paraîtront donc le dernier jeudi du mois.

Pas la fin

Ce blog fête aujourd’hui ses deux ans et demi d’existence. Cela représente un article par semaine au cours des 130 dernières semaines. J’ai toujours eu l’intention de réduire le temps que je consacre au blog cette année. Mais il est devenu évident que même avec les plans que j’avais mis en place pour me faciliter la vie, ce niveau de production est devenu insoutenable.

Les documents en tant que code ne sont pas forcément synonymes de Markdown et de Git

Après presque 15 ans en tant que rédacteur technique pour des sociétés de logiciels, je suis un converti à la philosophie de la documentation en tant que code. Mais si j’aime Markdown et Git (je les utilise pour ce site web), je ne les utiliserais pas pour documenter des logiciels d’entreprise. Je ne bénéficierais pas des avantages des outils de documentation dédiés, tels que la création structurée, la source unique et les PDF de haute qualité, pour n’en citer que quelques-uns. On vous a peut-être dit que vous deviez abandonner vos outils et devenir plus proche d’un développeur pour faire de la documentation en tant que code, mais je ne pense pas que ce soit vrai.

Quelles langues naturelles devriez-vous prendre en charge?

Je suis depuis longtemps un défenseur de la localisation (même si j’ai pris un peu de retard dans la traduction en français des anciens contenus de ce site). On peut supposer que, la plupart du temps, les lecteurs préfèrent accéder au contenu dans leur propre langue. Mais comme vos ressources sont limitées, quelles langues naturelles (et non informatiques) devriez-vous prendre en charge?

Le magazine informatique américain: 1957 à 2023

L’imprimé évolue mais, après 66 ans, l’ère du magazine informatique imprimé à grande échelle est révolue. Les deux derniers survivants étaient MacLife (anciennement MacAddict) et Maximum PC (anciennement Boot). Les numéros actuels sont les derniers. Comme j’ai commencé dans la presse écrite (avec un peu de radio à côté) et que je suis les tendances de l’informatique depuis près de 40 ans, j’ai quelques idées sur la question. Ce ne sera donc pas une répétition de l’excellent article de Harry McCracken sur le sujet dans Technologizer.

Utiliser LanguageTool pour améliorer votre écriture

Comme je l’ai déjà fait remarquer, j’ai manqué deux choses en passant du journalisme écrit à la rédaction technique. J’ai abordé les guides de style la semaine dernière, et cette fois-ci, ce sont les rédacteurs en chef (j’ai conservé mon addiction au café noir). Si vous devez rédiger des textes destinés aux clients et que vous avez la chance d’avoir un rédacteur, assurez-vous que son patron sait à quel point son travail est important pour le vôtre. Si ce n’est pas le cas, il existe des solutions logicielles qui peuvent vous aider.

Un blog sur l'industrie technologique

Lorsque j’ai commencé à écrire ce blog en 2022, je n’avais même pas de nom. Il s’appelait simplement Dev Blog. Mais il m’est venu à l’esprit que le titre de magazine que j’avais mis de côté pour un usage futur, “Byte High, No Limit”, serait idéal. Et en fait, je vais combiner des articles sélectionnés dans un format magazine (en partie pour garder la main sur la mise en page, et en partie pour apprendre à utiliser Affinity Publisher).