Cómo crear una base de conocimientos sobre desarrollo antes de su próximo trabajo

Cómo crear una base de conocimientos sobre desarrollo antes de su próximo trabajo

noviembre 29, 2021 0 Por RenzoC


Descargo de responsabilidad: este no es un anuncio de Obsidian.

Integrarse en un nuevo negocio es un trabajo duro. Mantener toda la información en orden es su propio flujo de trabajo que merece reflexión y atención. Innumerables nombres, rostros *, equipos, iniciativas y siglas desfilan antes del mediodía. Créeme. Estoy en el proceso ahora mismo. Esta semana aterricé en un sistema con el que estoy bastante contento.

Eres un trabajador del conocimiento. Construya una base de conocimientos

Necesita un lugar para poner toda la información que recibe. Estas son algunas de las cosas de las que estoy hablando:

  • Gente
  • Equipos
  • Depósitos
  • Relaciones entre equipos, repositorios, personas, etc.
  • Iniciativas
  • Tu producto de trabajo y tus tareas
  • «Playbooks» para tareas comunes
  • Diarios diarios
  • Notas de la reunión
  • Ideas
  • Preguntas que debes hacerle a alguien

Recomiendo obsidiana. Es básicamente un editor de rebajas, pero es mucho más que eso. Es de código abierto. Funciona desde su sistema de archivos local, sin preocupaciones de privacidad basadas en la nube. Le anima a crear una red de conocimiento densa con muchos enlaces y etiquetas. También tiene un amplio conjunto de complementos oficiales y comunitarios.

Semillas de planta

Puede resultar bastante intimidante empezar desde un directorio vacío. Pero no es necesario que cree su base de conocimientos manualmente. Intente sembrar a partir de fuentes de datos disponibles.

Wiki de ingeniería

¿Su organización tiene una wiki de ingeniería en GitHub? Clónelo y vacíelo directamente en su carpeta de obsidiana. Ahora tienes toneladas de páginas en lugar de una pizarra en blanco.

Eres el primer exportador de tu empresa en términos de integración. Nadie más recuerda cómo fue subir a bordo y, especialmente si lo hicieron hace mucho tiempo, la experiencia podría ser muy diferente ahora. Puede usar su perspectiva para mejorar la experiencia de incorporación del próximo empleado. Contribuya a la wiki durante su incorporación. Hazlo menos confuso.

Recomiendo consultar una rama del repositorio para que cualquier cambio que realice sea compatible con PR. Un cambio realmente simple que agrega mucho valor es simplemente agregar hipervínculos. A menudo hay una página oscura que describe algo que no está relacionado con ella. Los hipervínculos son una mejor herramienta de descubrimiento que grep, así que agréguelos.

Resto de Github

Agregue un archivo de rebajas a su base de conocimientos para cada repositorio de su organización. Si está utilizando GitHub, descargue la CLI de GitHub. A partir de ahí, puede generar un archivo JSON de los mejores repositorios de su organización … si puede, consígalos todos. Están ordenados por la confirmación más reciente.

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

También escribí un pequeño script de nodo para generar archivos de rebajas.

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)
  );
}

Personas y equipos

Éste es más difícil de hacer genérico. En mi nuevo trabajo, encontré una lista bastante buena de organizaciones de ingeniería en Grupos de Google, copié la tabla html del navegador a Hojas de cálculo de Google y luego exporté un archivo CSV. Tu fuente de verdad podría ser Slack, los equipos de GitHub o algo completamente diferente. También puede agregar personas manualmente.

Crea perfiles para todas las personas que conoces

Seguimiento de versiones

Usa git. Git init en su directorio de Obsidian. Usamos git para todo lo demás, ¿qué tal nuestra base de conocimientos? Comprométase al final de cada día y vea la diferencia. Escribe un mensaje de confirmación real. No se preocupe por la longitud. Para mí, contiene un mejor resumen de mi día que el que no puedo encontrar en ningún otro lugar.
$ git log ahora es una excelente manera de ver lo que ha estado haciendo en una semana.

Solo asegúrese de tener un archivo .gitignore. En mi caso, ignoro mi directorio eng-wiki para no tener que lidiar con los submódulos git.

Diagramas

Una imagen vale 1000 palabras. Así es como tomo fotografías.

Excalidraw

Hay un complemento Excalidraw para Obsidian (¡gracias @zsviczian!). Ya he escrito cuanto yo amor Excalidraw. El hecho de que Obsidian pueda caber elegantemente en Excalidraw es asombroso. Cuando digo con elegancia, lo digo en serio. Puede vincular diagramas internos a páginas de su base de conocimientos. Puede integrar. Está bien.

Excalidraw

Sirena

Excalidraw es una gran herramienta de diagramación de propósito general. Pero, para diagramas muy estructurados, Mermaid a veces es mejor. Obsidian tiene soporte nativo para diagramas de sirenas. Simplemente cree un bloque de código anotado como «sirena».

Aquí hay un ejemplo de sus documentos.


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

Sirena

Preguntas

Se harán 1.000.000 de preguntas todos los días. No siempre habrá tiempo para preguntarles. Puede buscar algunos de ellos. Recomiendo hacer un sistema para estos. Hice una página central de preguntas. Cuando aparecen cosas en otras páginas, hago un enlace a mi página de preguntas. De esta manera, cuando quiero revisar las preguntas abiertas, puedo ir y ver todos los vínculos de retroceso. Las balizas también funcionan.

Todos los días, eche un vistazo a las preguntas abiertas. Explore la wiki de la empresa u otras fuentes de información. Si encuentra la respuesta, actualice el enlace a [[question]] Para [[answered-question]] e incluya la respuesta con los hipervínculos al contenido existente en la base de conocimientos. Por ejemplo, [[answered-question]] what's the protocol for opening PRs into other teams' repos? Answer: [[eng-wiki/code-review-process]] goes into this.

Para las preguntas que no pueda responder por su cuenta, fíltrelas solo por las que sean importantes y su equipo pueda responderlas, y elimínelas en masa, todos los días. Asegúrese de que las respuestas vuelvan a su base de conocimientos.

Notas diarias

Nota del dia

Obsidian tiene un complemento de Notas diarias muy útil. Por la mañana, creo una nota diaria, entro en mi Calendario de Google (enlace de hipertexto a todas las personas con las que me encuentro). Siempre incluyo una sección «meta» para comentarios sobre cómo me sirve el sistema. También recomiendo crear enlaces que hagan referencia al día siguiente y al día anterior.

Encuentro que las notas diarias terminan acumulando un montón de cosas al azar que aparecieron ese día. Tómese un tiempo para considerar si es necesario mover el contenido de la página Notas diarias.

Entradas

Al menos inicialmente, todas las tareas que se le asignen para administrar sus productos también se pueden rastrear en su propio sistema de notas personal. Le permite vincular documentos relevantes, tomar notas, escribir actualizaciones de estado, recopilar preguntas, crear diagramas y más.

Billete

Mi directorio de entradas no es plano. El mío se ve así:


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

Tener la distinción entre abierto y cerrado ayuda a ponerse de pie cuando quiere decirle a su equipo cómo va el boleto.

La mayoría de las tareas que realiza cuando es nuevo en el trabajo son algo rutinarias. No cambia la arquitectura de la página de inicio la primera semana. Para estas tareas repetibles, ¿hay buena documentación sobre cómo hacer esto? Probablemente no. Haz un libro de jugadas. Será más fácil de hacer la próxima vez. Si su libro de jugadas describe algo más allá de usted y su equipo, agréguelo a la wiki en inglés.

Retro, escritura y síntesis libres

Si su equipo hace retrospectivas, le recomiendo que planee con tiempo de anticipación para escribir algo gratis. Incluso si su equipo no tiene una tradición retro, hacer tiempo para el pensamiento libre es una gran idea: fomenta la síntesis, la conexión y la comprensión.

Piense en ello como parte de la descripción de su trabajo para minimizar la entropía. Una vez que comprenda la bola de hilo que es su organización, puede desenredarla o al menos reducir la velocidad a la que se enreda. Puede idear analogías, diagramas, conexiones; lo que sea que haga que el sistema se adapte mejor al cerebro, agregará un valor tremendo. Aquí hay un gran artículo sobre esta idea general que se aplica a los investigadores. Lo llaman deuda de investigación. Lo considero como deuda semántica Dónde deuda cognitiva. La escritura reflexiva es una buena forma de preparar su cerebro para la síntesis.

Cuando escribes pensativamente. No se preocupe por el formato y los enlaces mientras escribe libremente, podría obstaculizar el flujo. Una vez que haya terminado, vea si hay algún enlace para agregar o algún formato para aplicar.

* ¡No ayuda que tenga prosopagnosia!

Este artículo de Off-by-one es una corriente de pensamiento en las computadoras. El autor Zeke Nierenberg escribe sobre programación, educación, herramientas de pensamiento tecnológico y desarrollo de productos. Encuentre el artículo original aquí.