Saltar a contenido

Guia de Technical Writing para Ingenieros

Proposito

Como escribir documentos tecnicos claros: specs, ADRs, RFCs, PRs, y mensajes de Slack. La habilidad de comunicar ideas tecnicas por escrito es tan importante como saber codificar.

1. Principios Fundamentales

Principio 1: Escribe para tu audiencia

Antes de escribir, preguntate: quien va a leer esto?

Audiencia Que necesitan Ejemplo
Otro engineer del equipo Contexto tecnico, decisiones, trade-offs ADR, PR description
Engineer nuevo Contexto completo, por que las cosas son como son System design, onboarding docs
PM / stakeholder Impacto, timeline, riesgos en lenguaje de negocio RFC, spec (secciones 1-2)
Tu yo futuro Por que tomaste esta decision hace 6 meses ADR, comentarios en codigo

Principio 2: Estructura antes que prosa

Los documentos tecnicos no son ensayos. Usa: - Headers para escaneo rapido. - Listas para enumerar items. - Tablas para comparaciones. - Codigo para ejemplos tecnicos. - Bold para resaltar lo mas importante de un parrafo.

Principio 3: Concreto sobre abstracto

MAL:  "El sistema debe ser performante y escalable."
BIEN: "El endpoint de busqueda debe responder en <500ms (p95) con 100 req/s."

Principio 4: Menos es mas

Si puedes decirlo en una oracion, no uses un parrafo. Si puedes decirlo en una tabla, no uses prosa.

2. Patrones por Tipo de Documento

Pull Request Description

## Que hace este PR
Implementa la cancelacion de turnos con politica de penalizacion (FEAT-002).

## Cambios principales
- Agrega `BookingCancellationService` con logica de penalizacion
- Nuevo endpoint: `PATCH /api/v1/bookings/:id/cancel`
- 12 unit tests + 5 integration tests

## Como testear
1. Crear un booking con `POST /api/v1/bookings`
2. Cancelar con `PATCH /api/v1/bookings/:id/cancel`
3. Verificar que si cancelas con <24h, el response incluye `cancellationPenalty: true`

## Decisiones tomadas
- Use bloqueo optimista en vez de pesimista para la concurrencia (ver comentario en linea X)
- El conteo de penalizaciones se resetea cada 6 meses (alineado con Product)

## Screenshots / Evidencia
[captura del test corriendo o del endpoint respondiendo]

Comentario de Code Review

MAL:  "Este codigo esta mal."
BIEN: "Este query no filtra por patientId, lo que permite que un paciente
       vea bookings de otro. Ver linea 45. Sugiero agregar:
       .where('booking.patientId = :patientId', { patientId })
       Esto esta relacionado con OWASP A01 (Broken Access Control)."

Mensaje de Slack tecnico

MAL:  "El deploy fallo. Alguien puede ver?"

BIEN: "El deploy a staging fallo en el stage de integration tests.
       - Error: Connection refused en test de booking creation
       - Causa probable: La BD de test no tiene la ultima migracion
       - Ya estoy investigando, actualizo en 15 min
       - Link al CI: [url]
       No bloqueante para produccion (staging solamente)."

3. Errores Comunes

Error Ejemplo Fix
Asumir contexto "Como saben, el servicio X..." "El servicio X (que maneja notificaciones)..."
Usar jerga innecesaria "Leveragear el paradigma reactivo" "Usar programacion reactiva para..."
Documentar el QUE sin el POR QUE "Usamos PostgreSQL" "Usamos PostgreSQL porque necesitamos transacciones ACID para evitar doble booking (ver ADR-001)"
Paredes de texto Un parrafo de 20 lineas Dividir en secciones con headers
No dar ejemplos "El formato de fechas debe ser estandar" "Las fechas usan ISO 8601: 2025-03-24T10:30:00Z"

4. Checklist antes de Enviar

  • Se entiende sin contexto adicional? (imagina que lo lee alguien que no estuvo en la reunion).
  • Tiene estructura clara? (headers, listas, tablas).
  • Los terminos tecnicos estan explicados la primera vez que aparecen?
  • Los ejemplos son concretos, no abstractos?
  • Es lo mas corto posible sin perder claridad?
  • Si incluye una decision, explica el POR QUE?

Checklist de Completitud

  • Principios fundamentales documentados
  • Patrones por tipo de documento con ejemplos
  • Errores comunes con fixes
  • Checklist antes de enviar
  • Revisada por otro ingeniero

Archivos relacionados