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


  • FrançaisFrançais


  • Avis de non-responsabilité : 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. Construire 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
    • Dépôts
    • Relations entre équipes, référentiels, personnes, etc.
    • Initiatives
    • Votre produit de travail et vos tâches
    • « Playbooks » pour les tâches courantes
    • Agendas quotidiens
    • Notes de réunion
    • Idées
    • Questions que vous devez poser à quelqu’un

    je recommande Obsidienne. 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 officiel et plugins de communauté.

    Graines de plantes

    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 de semer à partir des sources de données disponibles.

    Wiki d’ingénierie

    Votre organisation a-t-elle 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 le premier exportateur 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 pendant votre intégration. Rendez-le moins confus.

    Je recommande de consulter 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 dépôt de votre organisation. Si vous utilisez GitHub, téléchargez la CLI GitHub. De là, vous pouvez générer un fichier JSON du top ‘n’ repos dans votre organisation… si vous le pouvez, obtenez-les peut-être 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 également écrit un petit script de nœud pour générer des fichiers de démarques.

    const { writeFileSync } = require('fs');
    const repos = require('./your-repos.json');
    
    const pathToObsidian = '...';
    
    function renderMarkdown(repo) {
    	return `# [${repo.name}](https://github.com/yourorg/${repo.name})
    	
      >> whatever you want here, description is nice...<<`;
    }
    
    for (const repo of repos) {
    	writeFileSync(
    	  `${pathToObsidian}/repos/${repo.name}.md`, 
    	  renderMarkdown(repo)
      );
    }
    

    Les gens et les équipes

    Celui-ci est plus difficile à rendre générique. Dans mon nouveau travail, j’ai trouvé une assez bonne liste des organisations 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.

    Créez des profils pour chaque personne que vous rencontrez

    Suivi des versions

    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 trouver ailleurs.
    $ git log est maintenant un très bon moyen de voir ce que vous avez fait en une semaine.

    Assurez-vous simplement d’avoir un fichier .gitignore. Dans mon cas, j’ignore mon répertoire eng-wiki pour ne pas avoir à gérer les sous-modules git.

    Diagrammes

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

    Excalidraw

    Il y a un plugin Excalidraw pour Obsidian (merci @zsviczian !). j’ai déjà écrit sur combien je amour 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 bien.

    Excalidraw

    Sirène

    Excalidraw est un excellent outil de création de diagrammes à usage général. Mais, pour les diagrammes très structurés, Sirène c’est parfois mieux. 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 de leurs docs.

    
    flowchart TD
      A[Start] --> B{Is it?};
      B -- Yes --> C[OK];
      C --> D[Rethink];
      D --> B;
      B -- No ----> E[End];
    

    Sirène

    Des 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 [question] à [[answered-question]] et incluez la réponse avec tout lien hypertexte vers le contenu existant dans la base de connaissances. Par exemple, [[answered-question]] what's the protocol for opening PRs into other teams' repos? Answer: [[eng-wiki/code-review-process]] goes into this.

    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

    Note du jour

    L’obsidienne a un plugin de notes quotidiennes c’est très utile. Dès le matin, je crée une note quotidienne, j’entre dans mon agenda Google Calendar (lien hypertexte vers toutes les personnes avec qui 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 les jour suivant et précédent.

    Je trouve 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é.

    Des billets

    Au moins au début, chaque tâche qui vous est assignée dans la gestion de vos produits pourrait é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.

    Billet

    Mon répertoire de billets n’est pas plat. Le mien ressemble à ça :

    
    tickets
    ├── closed
    │   ├── POP-696.md
    │   └── POP-698.md
    └── open
        └── POP-700.md
    

    Avoir la distinction entre ouvert et fermé aide au stand-up 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 playbook décrit quelque chose au-delà de vous et de votre équipe, ajoutez-le au wiki à l’échelle de l’anglais.

    Rétros, écriture libre et synthèse

    Si votre équipe fait des rétros, je vous recommande de planifier un certain temps à l’avance pour faire de l’écriture libre. 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.

    Considérez-le comme faisant partie 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 tel qu’il s’applique aux chercheurs. Ils appellent cela la dette de recherche. je le considère comme dette sémantique ou dette cognitive. L’écriture réflexive 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.

    *Cela n’aide pas que j’aie une prosopagnosie !

    Cet article de Un par un est un courant de pensée 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. Retrouver l’article d’origine ici.

    Source

    N'oubliez pas de voter pour cet article !
    1 Star2 Stars3 Stars4 Stars5 Stars (No Ratings Yet)
    Loading...

    Houssen Moshinaly

    Rédacteur web depuis 2009 et webmestre depuis 2011.

    Je m'intéresse à tous les sujets comme la politique, la culture, la géopolitique, l'économie ou la technologie. Toute information permettant d'éclairer mon esprit et donc, le vôtre, dans un monde obscur et à la dérive.

    Je suis l'auteur de plusieurs livre

    Pour me contacter personnellement :

    Laisser un commentaire

    Votre adresse e-mail ne sera pas publiée.