Comment créer une base de connaissances de développement avant votre prochain travail

Avertissement : ce n'est pas une annonce pour Obsidian.

L'intégration dans une nouvelle entreprise est un travail difficile. Garder toutes les informations droites est son propre flux de travail qui mérite réflexion et attention. D'innombrables noms, visages*, équipes, initiatives et acronymes défilent avant midi. Crois-moi. Je suis dans le processus en ce moment. Cette semaine, j'ai atterri sur un système dont je suis assez satisfait.

Vous êtes un travailleur du savoir. Construisez une base de connaissances

Vous avez besoin d'un endroit pour mettre toutes les informations que vous recevez. Voici quelques-unes des choses dont je parle :

• Personnes
• Équipes
• Référentiels
• Relations entre équipes, référentiels, personnes, etc.
• Initiatives
• Votre produit de travail et tâches[19659008]« Playbooks » pour les tâches courantes
• Agendas quotidiens
• Notes de réunion
• Idées
• Questions à poser à quelqu'un

Je recommande Obsidian. C'est essentiellement un éditeur de démarques, mais c'est bien plus que cela. C'est open source. Il fonctionne à partir de votre système de fichiers local, sans aucun problème de confidentialité basé sur le cloud. Il vous encourage à créer un réseau de connaissances dense avec de nombreux liens et balises. Il dispose également d'un riche ensemble de plugins officiels et communautaires.

Plant seeds

Il peut être assez intimidant de démarrer à partir d'un répertoire vide. Mais vous n'avez pas besoin de créer votre base de connaissances manuellement. Essayez l'ensemencement à partir des sources de données disponibles.

Wiki d'ingénierie

Votre organisation dispose-t-elle d'un wiki d'ingénierie sur GitHub ? Clonez-le et videz-le directement dans votre dossier Obsidian. Maintenant, vous avez des tonnes de pages au lieu d'une ardoise vierge.

Vous êtes la principale exportation de votre entreprise en matière d'intégration. Personne d'autre ne se souvient de ce que c'était que d'embarquer, et – surtout s'ils ont embarqué il y a longtemps – l'expérience pourrait être très différente, maintenant. Vous pouvez utiliser votre point de vue pour améliorer l'expérience d'intégration du prochain employé. Contribuez au wiki lors de votre intégration. Rendez les choses moins confuses.

Je recommande de vérifier une branche du référentiel afin que toutes les modifications que vous apportez soient compatibles avec les relations publiques. Un changement vraiment simple qui ajoute une tonne de valeur consiste simplement à ajouter des hyperliens. Il y a souvent une page obscure décrivant quelque chose qui n'a aucun lien vers elle. Les hyperliens sont un meilleur outil de découverte que grep, alors ajoutez-les.

Repos Github

Ajoutez un fichier de démarques dans votre base de connaissances pour chaque repo de votre organisation. Si vous utilisez GitHub, téléchargez la CLI GitHub. À partir de là, vous pouvez générer un fichier JSON du premier « n » repos de votre organisation… si vous le pouvez, obtenez-les tous. Ils sont classés par commit le plus récent.

$ gh repo list [yourorgname] --limit 1000 --json name,description,createdAt,updatedAt`) > your-repos.json

J'ai écrit un petit script de nœud pour générer également des fichiers de démarque.

const { writeFileSync } = require('fs');
const repos = require('./votre-repos.json');

const cheminVersObsidienne = '...';

fonction renderMarkdown(dépôt) {
return `# [${repo.name}](https://github.com/yourorg/${repo.name})

  >> tout ce que vous voulez ici, la description est sympa...<<`;
}

pour (const repo de repos) {
writeFileSync(
`${cheminVersObsidienne}/dépôt/${dépôt.nom}.md`,
renderMarkdown(dépôt)
  );
}

Personnes et équipes

Celui-ci est plus difficile à rendre générique. Dans mon nouveau travail, j'ai trouvé une assez bonne liste de l'organisation d'ingénierie dans Google Groups, j'ai copié le tableau html du navigateur dans des feuilles Google, puis j'ai exporté un fichier CSV. Votre source de vérité peut être Slack, les équipes GitHub ou quelque chose de totalement différent. Vous pouvez également ajouter des personnes manuellement.

Suivi de version

Utilisez git. Git init dans votre répertoire Obsidian. Nous utilisons git pour tout le reste, pourquoi pas notre base de connaissances ? Engagez-vous à la fin de chaque journée et jetez un œil à la différence. Écrivez un vrai message de commit. Ne vous inquiétez pas de la longueur. Pour moi, il contient un meilleur résumé de ma journée que je ne peux en trouver ailleurs.
$ git log est maintenant un très bon moyen de voir ce que vous avez fait en une semaine.

Assurez-vous simplement vous avez un fichier .gitignore. Dans mon cas, j'ignore mon répertoire eng-wiki donc je n'ai pas à m'occuper des sous-modules git.

Diagrammes

Une image vaut 1000 mots. Voici comment je fais des images.

Excalidraw

Il y a un plugin Excalidraw pour Obsidian (merci @zsviczian!). J'ai déjà écrit sur combien j'aime Excalidraw. Le fait qu'Obsidian puisse s'intégrer avec élégance à Excalidraw est incroyable. Quand je dis élégamment, je le pense vraiment. Vous pouvez lier des diagrammes internes à des pages de votre base de connaissances. Vous pouvez intégrer. C'est génial.

Sirène

Excalidraw est un excellent outil de création de diagrammes à usage général. Mais, pour des diagrammes très structurés, Mermaid est parfois meilleur. Obsidian a un support natif pour les diagrammes de sirène. Créez simplement un bloc de code annoté comme « sirène ».

Voici un exemple tiré de leur documentation.

organigramme TD
  A[Start] --> B{Est-ce ?} ;
  B -- Oui --> C[OK] ;
  C --> D[Rethink];
  D --> B ;
  B -- Non ----> E[End] ;

Questions

1 000 000 de questions seront posées chaque jour. Il n'y aura pas toujours le temps de leur demander. Vous pouvez rechercher certains d'entre eux. Je recommande de faire un système pour ceux-ci. J'ai fait une page de questions centrale. Lorsque des choses se présentent sur d'autres pages, je crée un lien vers ma page de questions. De cette façon, lorsque je veux revoir les questions ouvertes, je peux aller voir tous les backlinks. Les balises fonctionnent également.

Chaque jour, jetez un œil aux questions ouvertes. Parcourez le wiki de l'entreprise ou d'autres sources de vérité. Si vous trouvez la réponse, mettez à jour le lien de à [[answered-question]] et incluez la réponse avec tout lien hypertexte vers le contenu existant dans la base de connaissances. Par exemple, [[answered-question]] quel est le protocole d'ouverture des PR dans les dépôts d'autres équipes ? Réponse : [[eng-wiki/code-review-process]] va dans ce sens.

Pour les questions auxquelles vous ne pouvez pas répondre par vous-même, filtrez-les uniquement sur celles qui comptent et auxquelles votre équipe peut répondre, et relâchez-les en masse, chaque jour. Assurez-vous que les réponses reviennent dans votre base de connaissances.

Notes quotidiennes

Obsidian a un plugin de notes quotidiennes qui est très utile. À la première heure du matin, je crée une note quotidienne, entre dans mon agenda Google Calendar (lien hypertexte vers toutes les personnes avec lesquelles je rencontre). J'inclus toujours une section « méta » pour des observations sur la façon dont le système me sert. Je recommande également de créer des liens référençant le le jour suivant et le jour précédent.

Je constate que les notes quotidiennes finissent par accumuler une tonne de choses aléatoires qui sont apparues ce jour-là. Prenez un peu de temps pour vous demander si le contenu de la page de notes quotidiennes doit être déplacé.

Tickets

Au moins au début, chaque tâche qui vous est assignée dans la gestion de vos produits peut également être suivie dans votre propre système de notes personnel. . Il vous permet de créer des liens vers des documents pertinents, de prendre des notes, de rédiger des mises à jour de statut, de rassembler des questions, de créer des diagrammes, etc.

Mon répertoire de tickets n'est pas appartement. Le mien ressemble à ceci :

des billets
fermé
├── POP-696.md
└── POP-698.md
ouvrir
    POP-700.md

Faire la distinction entre ouvert et fermé aide à se lever lorsque vous voulez dire à votre équipe comment se passe le ticket.

La plupart des tâches que vous effectuez lorsque vous êtes nouveau au travail sont quelque peu par cœur. Vous ne modifiez pas l'architecture de la page d'accueil la première semaine. Pour ces tâches répétables, existe-t-il une bonne documentation sur la façon de procéder ? Probablement pas. Faites un livre de jeu. Ce sera plus facile à faire la prochaine fois. Si votre livre de jeu décrit quelque chose au-delà de vous et de votre équipe, ajoutez-le au wiki à l'échelle de l'anglais. . Même si votre équipe n'a pas de tradition rétro, prévoir du temps pour une réflexion libre est une excellente idée – cela encourage la synthèse, les connexions et la compréhension.

Pensez-y dans le cadre de votre description de poste pour minimiser l'entropie. . Après avoir compris la pelote de laine qu'est votre organisation, vous pouvez la démêler, ou au moins réduire la vitesse à laquelle elle s'emmêle. Vous pouvez proposer des analogies, des diagrammes, des connexions – tout ce qui permet au système de mieux s'intégrer dans les cerveaux – vous ajouterez une valeur énorme. Voici un excellent article sur cette idée générale telle qu'elle s'applique aux chercheurs. Ils appellent cela la dette de recherche. Je le considère comme une dette sémantique ou dette cognitive. L'écriture réfléchie est un bon moyen de préparer votre cerveau à la synthèse.

Lorsque vous écrivez de manière réfléchie. Ne vous inquiétez pas du formatage et des liens pendant que vous écrivez librement, cela pourrait gêner le flux. Une fois que vous avez terminé, voyez s'il y a des liens à ajouter ou une mise en forme à appliquer.

*Ça n'aide pas que j'ai une prosopagnosie !

Cet article de Off-by -one est un courant de réflexion sur les ordinateurs. L'auteur, Zeke Nierenberg, écrit sur la programmation, l'éducation, les outils de réflexion technologiques et le développement de produits. Trouvez l'article original ici.