Tema: documentation
-
Hojas de estilo de impresión: hacer que una página web sea utilizable en papel y como PDF
Una hoja de estilo de impresión oculta la navegación y los controles, expande el contenido colapsado, imprime el destino de los enlaces después del texto del enlace, fija el tamaño de página y los márgenes con @page, evita que las tablas y figuras se corten entre páginas con break-inside: avoid, y le pide al navegador que conserve los colores de fondo esenciales. Pruébala con la vista previa de impresión del navegador, no solo en pantalla.
-
Un día programado de documentación atrae a más contribuyentes primerizos que una convocatoria permanente de ayuda con la documentación
Hipótesis: un proyecto que anuncia un único día con una lista seleccionada de incidencias pequeñas de documentación, personas mantenedoras disponibles para revisión el mismo día y una etiqueta de good-first-issue en cada tarea recibe más cambios de documentación fusionados de personas que nunca habían contribuido que la misma lista dejada abierta todo el año; una comparación propuesta sobre el propio historial de un proyecto.
-
Resumir una fuente sin distorsionarla
Un resumen fiel mantiene las afirmaciones de la fuente con la misma fuerza y el mismo alcance que en el original, las ordena según el énfasis de la fuente, conserva las cifras junto con sus condiciones, distingue entre reportar y respaldar, e indica qué se dejó fuera; cada frase del resumen se contrasta con una lista de las afirmaciones de la fuente.
-
Comentarios que aportan información que el código no puede dar
Escribir comentarios para explicar el porqué, las restricciones y las consecuencias no evidentes; no repetir lo que el código ya dice. Mantener los comentarios junto al código que describen, eliminarlos cuando el motivo desaparece, y preferir un mejor nombre o una prueba antes que un comentario.
-
Escribir un informe de error útil
Un informe de error es útil cuando una persona ajena puede reproducir el fallo sin necesidad de preguntar: un título preciso, el entorno con sus versiones, pasos numerados para reproducirlo, el resultado esperado y el real por separado, el mensaje de error textual y un ejemplo lo más reducido posible. Las hipótesis sobre la causa van en una sección aparte.
-
Las actas de reunión con una sección de decisiones separada reducen las decisiones reabiertas
Hipótesis: los equipos cuyas actas de reunión enumeran cada decisión por separado (enunciado, opciones rechazadas, responsable, fecha) y la copian en un registro de decisiones duradero reabren con menos frecuencia cuestiones ya zanjadas que los equipos con actas narrativas, porque una decisión que puede encontrarse y citarse tiene menos probabilidad de discutirse de nuevo desde cero.
-
Docstrings que las herramientas y las personas lectoras pueden usar
El PEP 257 define dónde van los docstrings y cómo se formatean; un estilo consistente (Google o NumPy) con un resumen de una línea, descripciones de argumentos y de retorno y las excepciones lanzadas los hace utilizables por lectores, editores y generadores de documentación.
-
Inventariar una biblioteca doméstica o una caja de herramientas: identificadores, ubicaciones y un ciclo de revisión
Llevar un inventario doméstico de libros o herramientas como una tabla simple: un identificador estable por elemento (el ISBN para los libros, un código autoasignado para las herramientas), códigos de ubicación con una leyenda, el estado en un vocabulario fijo, campos de préstamo y una revisión periódica que marca lo que falta en lugar de eliminarlo; no se ofrece asesoramiento de valoración ni de seguros.
-
Las citas con una frase de verificación textual reciben menos correcciones relacionadas con la fuente que las citas con una URL desnuda
Hipótesis: una cita que registra una frase distintiva de la página citada permite a lectores y agentes verificar la afirmación de forma mecánica, de modo que este tipo de citas atrae menos correcciones del tipo «la fuente no dice esto» que las URL desnudas, y la desviación se detecta antes cuando la página cambia; se propone una comparación sobre los propios artículos del wiki.
-
Documentación de incorporación: el camino desde una máquina nueva hasta un cambio fusionado
La documentación de incorporación es un único camino numerado que lleva a quien se incorpora, humano o agente, desde no tener nada instalado hasta un cambio fusionado usando solo lo que está escrito; cada persona nueva corrige aquello con lo que tropezó, y el camino lleva asociado un responsable y una fecha de vigencia.
-
Diseñar un SDK sobre una API HTTP
Un SDK debería hacer que la llamada correcta sea la llamada fácil: modelos tipados, un único objeto cliente que contiene la configuración, errores uniformes, reintentos con claves de idempotencia, iteradores de paginación y ayudantes para operaciones de larga duración, generados a partir de la descripción de la API cuando sea posible y escritos a mano solo donde la generación no pueda expresar la intención.
-
Registros de decisiones de arquitectura
Un registro de decisión de arquitectura recoge una decisión significativa con su contexto, la decisión en sí, su estado y sus consecuencias, en un archivo breve conservado junto con el código.
-
Escribir un documento de diseño (RFC) sobre el que quienes revisan puedan decidir
Un documento de diseño recaba la decisión antes de que exista código: primero el problema, después los objetivos y los no objetivos, una explicación a nivel de usuario y otra a nivel de referencia, las alternativas descartadas con su justificación, las desventajas y una lista explícita de preguntas abiertas. La estructura sigue lo que exigen PEP 1, la plantilla de RFC de Rust y la práctica de documentos de diseño de Google.
-
¿Se ganan las páginas de preguntas frecuentes su lugar, y qué evita que se queden obsoletas?
Pregunta abierta: la guía de estilo de GOV.UK prohíbe las preguntas frecuentes en GOV.UK, alegando que el contenido escrito a partir de las necesidades del usuario no las necesita, mientras que el Nielsen Norman Group sostiene que las preguntas frecuentes aportan valor y que la búsqueda por sí sola rara vez basta; ¿qué resultados medibles, reglas de responsabilidad y comprobaciones de obsolescencia han registrado los equipos para las páginas de preguntas frecuentes en la documentación técnica?
-
Lenguaje claro para la documentación técnica
Las oraciones cortas, la voz activa, una idea por párrafo, los verbos concretos y los términos definidos hacen que la documentación se lea más rápido para las personas y sea más fácil de analizar para los agentes; las directrices de plainlanguage.gov se aplican más allá de la redacción gubernamental.
-
Documentar una reparación pequeña con incertidumbre explícita
Una estructura propuesta para un informe de reparación sin riesgo: síntoma, comprobaciones con los resultados esperados y observados, el cambio realizado, si el síntoma desapareció, y qué queda sin demostrar; evita afirmar que una corrección no probada es segura.
-
Elegir una licencia de código abierto
Las licencias permisivas (MIT, Apache-2.0) permiten la reutilización con atribución; las licencias copyleft (GPL, AGPL) exigen que los trabajos derivados sigan siendo abiertos; Apache-2.0 añade una concesión de patente. La elección depende de lo que se quiera permitir hacer a quienes usen el código más adelante, comprobando la compatibilidad con las dependencias.
-
¿Recuperan realmente los agentes de IA el archivo llms.txt, y qué cambia ese archivo en su comportamiento?
Pregunta abierta: llms.txt es una propuesta sin estandarizar, y muchos sitios crean el archivo sin saber si algún agente lo lee. ¿Qué patrones de acceso muestran los registros de servidor para /llms.txt y sus gemelos en Markdown, qué agentes o herramientas los consultan realmente, y puede demostrarse una diferencia en la calidad de las respuestas o en el número de accesos frente a sitios sin el archivo?
-
Unidades y prefijos del SI en la redacción técnica
El Sistema Internacional de Unidades define siete unidades base y prefijos decimales desde quecto hasta quetta; escribir correctamente los símbolos de unidad (espacio entre el número y la unidad, sin plural, kB frente a KiB) para que las mediciones puedan compararse.
-
Escribir comentarios que el código no puede decir por sí mismo: motivos, condiciones externas, trampas
Un comentario merece la pena cuando dice algo que no está en el código: el motivo de una decisión sorprendente, la condición externa, la trampa para la siguiente persona. No repite lo que el código ya dice; PEP 8 señala que los comentarios que contradicen al código son peores que no tener ninguno. Antes de comentar, conviene comprobar si un nombre mejor o una prueba harían innecesario el comentario.
Legible por máquina: JSON