Una estantería de libros ya no es un plan de aprendizaje
En 2026 una bibliografía envejece más rápido que antes. Los flujos de Git, las comprobaciones automáticas y la IA generativa forman parte del trabajo, mientras que las guías públicas cambian durante el año. Los libros siguen siendo buenos para desarrollar ideas largas; una guía viva responde mejor a dudas concretas de estilo, código, UI o procedimientos.
Microsoft y Google mantienen guías públicas, GitHub explica su modelo de contenido, IBM publica estándares de calidad y Diátaxis ofrece una estructura práctica para separar tipos de documentación.
Cinco guías vivas que conviene tener abiertas
| Fuente | Punto fuerte | Idea práctica |
|---|---|---|
| Microsoft | Voz, procedimientos, UI | Frases simples, voz activa y acciones directas |
| Developer docs y audiencia global | Condiciones antes de instrucciones; entidades técnicas como código | |
| GitHub Docs | Objetivo del usuario y estructura | Publicar solo lo necesario y elegir un tipo de contenido |
| IBM | Evaluación de calidad | Separar accuracy, completeness, clarity, organization y retrievability |
| Diátaxis | Arquitectura | No mezclar tutorial, how-to, reference y explanation sin motivo |
Compare el mismo problema entre tradiciones
Texto pobre: “Para completar correctamente la operación, los usuarios deben asegurarse de que el repositorio haya sido inicializado antes de hacer clic en Create.”
Microsoft empuja hacia “Inicialice el repositorio y seleccione Create”. Google puede poner primero la condición: “Antes de seleccionar Create, inicialice el repositorio”. GitHub pregunta por el objetivo: “Para crear el proyecto, inicialice el repositorio y seleccione Create”. IBM además verifica si el requisito es verdadero y si falta el resultado. Diátaxis pregunta si esta instrucción debe estar en una página reference o en un how-to.
Estudie un problema cada vez, con una tarea real
| Problema | Compare | Ejercicio | Resultado |
|---|---|---|---|
| Prerequisites ocultos | Microsoft + Google | Reescribir un procedimiento real | Before/after y regla local |
| API reference demasiado narrativa | Diátaxis + Google | Separar hechos de escenario | Reference limpia + how-to |
| Terminología variable | Google + Microsoft | Auditar 20 términos | Glosario y reglas de lint |
| Review repetitivo | IBM + GitHub | Separar comentarios de máquina y humanos | Checklist de review |
| Prosa difícil de localizar | Google + IBM | Quitar ambigüedad de dos páginas | Ejemplos locales |
Convierta la lectura en habilidad
Empiece con un defecto real, compare dos o tres fuentes, escriba la regla con sus palabras, cambie una página y compruebe el resultado con un lector o SME. Si la solución se repite, pásela al style guide o a una comprobación automática. El registro de aprendizaje debe conservar el fragmento original, la versión nueva y el resultado del review.
Libros que aún ayudan y qué ha envejecido
Docs for Developers (2021) sigue siendo útil por su ciclo completo desde audiencia hasta mantenimiento, aunque no cubre la actual ola de LLM. Developing Quality Technical Information (2014) conserva un modelo de calidad muy fuerte, aunque parte del contexto de delivery es anterior a Docs-as-Code moderno. Every Page Is Page One (2013) sigue siendo útil para pensar en páginas encontradas desde búsqueda, pero hoy también existen respuestas de IA y portales distintos. The Product is Docs aporta una buena mirada al trabajo transversal dentro del equipo de producto.
Construya su propio style guide con decisiones probadas
Una guía externa es referencia, no constitución. Cuando el mismo término genera tres debates, decídalo localmente. Cuando los ejemplos API tienen estructuras distintas, fije un patrón. Guarde problema, decisión, ejemplo y excepción.
| Campo | Ejemplo |
|---|---|
| Problema | log in, login y sign in describen una acción |
| Decisión | Use sign in para la acción; conserve nombres técnicos literales |
| Ejemplo | “Sign in to the admin console.” |
| Excepción | Un campo API llamado login no cambia |
Qué hacer esta semana
Elija una página que ya tenga un comentario real. Formule el problema, compare dos fuentes y cree una versión before/after. Muéstrela a una persona que use la documentación y conserve la regla solo si mejora el resultado. Una semana produce así una página mejor y una decisión probada, no solo capítulos leídos.
