Artículo Técnico

Instrucciones para agentes de IA sobre cómo crear, revisar y actualizar artículos técnicos utilizando lenguaje formal, estructura coherente, terminología precisa, ejemplos prácticos y referencias verificables.

1. Beneficios
2. Principios
- 2.1. Lenguaje
- 2.2. Integridad del Contenido
3. Estructura
4. Flujo de Trabajo
5. Guía de Estilo
6. Puertas de Calidad
7. Recursos
8. Referencias

1. Beneficios

Consistencia

Una gramática de artículo estable hace que el contenido técnico sea predecible entre temas y permite a los lectores localizar definiciones, categorías, principios, ejemplos y referencias sin tener que reaprender la estructura del documento.
Legibilidad

Los párrafos de definición concisa, los encabezados explícitos y las listas de definiciones de términos reducen la carga cognitiva mientras preservan la precisión técnica.
Navegabilidad

Una tabla de contenido jerárquica mantenida manualmente y los encabezados numerados exponen la jerarquía conceptual y proporcionan navegación directa para artículos largos.
Reutilización

Las taxonomías, listas de terminología, ejemplos prácticos y referencias calificadas hacen que cada artículo sea útil tanto como introducción como referencia de ingeniería duradera.
Capacidad de Revisión

El formato determinista y las reglas de evidencia permiten a los revisores separar defectos estructurales, defectos de lenguaje e imprecisiones técnicas.

2. Principios

2.1. Lenguaje

Formal

Utilice inglés neutro adecuado para ingenieros de software, ingenieros de sistemas, profesionales de seguridad y tomadores de decisiones técnicas.
Enciclopédico

Defina el tema antes de prescribir prácticas. Explique qué es un concepto, cómo se categoriza y dónde se aplica antes de presentar recomendaciones.
Preciso

Prefiera sustantivos y verbos específicos del dominio en lugar de palabras amplias o promocionales. Distinga entre estándares, especificaciones, protocolos, herramientas, marcos de trabajo, prácticas, métricas y patrones arquitectónicos.
Impersonal

Prefiera construcciones en tercera persona o impersonales. Evite la narración en primera persona, la dirección directa en segunda persona, las preguntas retóricas y el relleno conversacional.
Declarativo

Exprese definiciones, relaciones, restricciones y resultados directamente. Use verbos modales solo cuando exprese un requisito real, recomendación, posibilidad o incertidumbre.

2.2. Integridad del Contenido

Evidencia

Respalde afirmaciones verificables externamente con fuentes autorizadas. Prefiera organismos de estandarización, documentación oficial, investigación primaria y repositorios canónicos.
Actualidad

Verifique datos sensibles al tiempo, comportamiento específico de versiones, umbrales de rendimiento, requisitos legales y capacidades del producto antes de incluirlos.
Alcance

Mantenga cada artículo centrado en un tema técnico. Enlace a artículos adyacentes en lugar de duplicar material de antecedentes sustancial.
Coherencia Taxonómica

Agrupe conceptos por una dimensión de clasificación explícita a la vez. No mezcle herramientas, prácticas, resultados y propiedades como pares a menos que la sección explique la relación.
Ejemplos

Utilice ejemplos que sean sintácticamente válidos, técnicamente plausibles y directamente conectados con la explicación anterior.

3. Estructura

3.1. Archivo y Título

Nombre de Archivo

Utilice un nombre de archivo en minúsculas con formato kebab-case que identifique el tema, por ejemplo technical-debt.md, feature-flags.md o file-systems.md.
Frontmatter

No agregue frontmatter YAML a los archivos de artículo a menos que el repositorio de destino lo requiera explícitamente.
Título H1

Comience con exactamente un encabezado H1 que contenga el nombre canónico del tema en formato de título.
```
# Feature Flags
```

3.2. Introducción

Coloque uno o dos párrafos concisos inmediatamente después del encabezado H1.

Definición

Defina el tema en la primera oración. Expanda un acrónimo en su primer uso cuando no sea universalmente evidente en el dominio del artículo.
Contexto

Explique el propósito, el rol operativo o la relación del tema con la ingeniería de software. No introduzca taxonomías detalladas antes de la tabla de contenido.

Ejemplo:

# Feature Flags

Los feature flags son controles en tiempo de ejecución que permiten habilitar o deshabilitar el comportamiento de una aplicación sin necesidad de un nuevo despliegue. Desacoplan el despliegue de código del lanzamiento de funcionalidades y respaldan el despliegue controlado, la experimentación y la mitigación operativa.

3.3. Tabla de Contenidos

Inserte una tabla de contenido Markdown mantenida manualmente después de la introducción y antes de la primera sección H2.

Jerarquía

Refleje cada encabezado H2, H3 y H4 material numerado usando sangría de dos espacios por nivel.
Etiquetas

Incluya el prefijo numérico completo y el texto del encabezado.
Anclas

Utilice anclas en minúsculas compatibles con GitHub. Elimine la puntuación de acuerdo con las reglas de encabezado de GitHub mientras preserva los guiones entre palabras.
Integridad

Agregue, elimine o renombre entradas de la tabla de contenido siempre que cambien los encabezados.

Ejemplo:

- [1. Categoría](#1-categoría)
  - [1.1. Estrategias de Despliegue](#11-estrategias-de-despliegue)
    - [1.1.1. Despliegue Azul-Verde](#111-despliegue-azul-verde)
    - [1.1.2. Despliegue Canario](#112-despliegue-canario)
- [2. Principio](#2-principio)
- [3. Mejor Práctica](#3-mejor-práctica)
- [4. Terminología](#4-terminología)
- [5. Referencias](#5-referencias)

3.4. Secciones Numeradas

Utilice numeración decimal arábiga en cada encabezado de artículo por debajo de H1.

H2

Use ## 1. <Sección> para secciones de nivel superior.
H3

Use ### 1.1. <Subsección> para secciones de segundo nivel.
H4

Use #### 1.1.1. <Tema> solo cuando una subsección contenga una taxonomía sustancial que requiera otro nivel.
Profundidad

Prefiera no más de cuatro niveles de encabezado incluyendo H1. Reemplace la profundidad excesiva de encabezados con listas de definiciones de términos o tablas.
Secciones Canónicas

Seleccione solo secciones que contribuyan al tema. Las etiquetas comunes compatibles con el corpus incluyen Beneficios, Categoría, Principio, Principios, Mejor Práctica, Terminología y Referencias.
Orden

Comience con conceptos y categorías fundamentales, continúe con principios o prácticas, luego concluya con terminología y referencias.

3.5. Taxonomías y Definiciones

Utilice prosa para transiciones conceptuales y listas de definiciones de términos para contenido técnico escaneable.

Encabezado de Sección

Abra una sección importante con uno o dos párrafos que expliquen la dimensión de clasificación o el propósito de la sección.

Patrón de Definición de Término

Presente una etiqueta técnica como viñeta y su explicación como una cita en bloque sangrada.

- Atomicidad
  > La atomicidad asegura que una transacción se complete como una unidad o se revierta sin retener un resultado parcial.

Patrón Agrupado

Utilice un elemento de lista ordenada como encabezado de grupo local cuando una subsección contenga varias vistas distintas, como convenciones, ejemplos o herramientas.
Capitalización de Etiquetas

Use formato de título para etiquetas conceptuales y formato de oración para descripciones.
Calidad de la Descripción

Comience las descripciones con el rol, comportamiento o propiedad definitoria del término. Evite definiciones circulares que repitan la etiqueta sin agregar significado.

3.6. Ejemplos y Datos

Ejemplos Independientes

Introduzca ejemplos independientes a nivel de prosa con Ejemplo:. Dentro de subsecciones agrupadas como Ejemplos y Explicaciones, use una etiqueta de ejemplo descriptiva en su lugar.
Ejemplos de Código

Use un bloque de código delimitado con el identificador de lenguaje más preciso.
Sintaxis en Línea

Use comillas invertidas para comandos, rutas de archivo, claves de configuración, identificadores, literales y fragmentos de sintaxis cortos.
Tablas

Use tablas Markdown para comparaciones compactas, matrices, métricas, comandos o datos de referencia enumerados. Mantenga el contenido de las celdas paralelo y evite párrafos en prosa dentro de las celdas.
Diagramas

Use diagramas basados en texto como Mermaid cuando las relaciones o los flujos no se puedan explicar eficientemente con prosa o una tabla.
Advertencias

Use advertencias de GitHub con moderación para restricciones, advertencias, enlaces cruzados o información que cambie materialmente la interpretación.
```
> [!NOTA]
> El umbral métrico depende del período de informe citado y debe verificarse antes de la publicación.
```

3.7. Referencias

Termine cada artículo con una sección Referencias numerada.

Referencias Internas

Use enlaces relativos al repositorio para artículos relacionados de Sentenz.
```
- Sentenz Artículo [Versionado](../articles/versioning.md).
```

Referencias Externas

Nombre la organización o el editor antes del título vinculado e identifique el tipo de fuente después del enlace.

- Publicación NIST [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final).
- Documentación Kubernetes [Documentación](https://kubernetes.io/docs/).
- Repositorio GitHub [DORA Four Keys](https://github.com/dora-team/fourkeys).

Tipos de Fuente

Use un calificador preciso como artículo, documentación, página, publicación, repositorio, informe, especificación o estándar.
Relevancia

Incluya solo fuentes citadas o utilizadas materialmente en el artículo. No cree una lista de lectura general no relacionada con las afirmaciones del artículo.

4. Flujo de Trabajo

4.1. Crear

Inspeccionar

Lea los archivos vecinos en el directorio de artículos de destino. Registre el vocabulario de encabezados local, el estilo de enlaces, las convenciones de bloques de código y los artículos internos relacionados.
Alcance

Defina el tema del artículo, la profundidad prevista y la dimensión de clasificación principal. Separe los temas adyacentes en artículos enlazados.
Investigar

Recolecte fuentes primarias autorizadas. Verifique terminología, estándares, métricas, comportamiento del producto y detalles sensibles al tiempo.
Esquema

Seleccione las secciones canónicas requeridas y construya una jerarquía de encabezados numerados antes de redactar la prosa.
Cargar Plantilla

Cargue assets/technical-article-template.md al crear un nuevo artículo. Elimine las secciones que no contribuyan al tema.
Redactar Introducción

Escriba el título H1 y uno o dos párrafos de definición. Establezca el tema y el contexto de ingeniería sin adelantar detalles de implementación.
Construir Tabla de Contenidos

Refleje la jerarquía de encabezados planificada y genere anclas exactas compatibles con GitHub.
Escribir Secciones

Agregue encabezados de sección, listas de definiciones de términos, ejemplos, tablas, diagramas y advertencias solo cuando mejoren la comprensión.
Agregar Referencias

Agregue enlaces relativos internos y referencias externas calificadas por fuente. Asegúrese de que cada afirmación externa material tenga una fuente autorizada adecuada.
Validar

Aplique todas las Puertas de Calidad antes de devolver o confirmar el artículo.

4.2. Revisar

Preservar la Intención

Identifique el tema, alcance y taxonomía del artículo existente antes de cambiar la estructura.
Cargar Plantilla

Cargue assets/technical-article-template.md antes de revisar el artículo. Úsela como línea base estructural, elimine las secciones de plantilla no aplicables y conserve las secciones válidas específicas del artículo.
Diagnosticar

Separe los defectos en precisión técnica, taxonomía, organización, lenguaje, formato, enlaces, ejemplos y referencias.
Normalizar

Alinee el título, la introducción, la tabla de contenido, la numeración, los niveles de encabezado, las listas, las citas en bloque, los bloques de código y las referencias con esta habilidad.
Refinar el Lenguaje

Reemplace palabras vagas, repetitivas, conversacionales o promocionales con definiciones técnicas directas y verbos apropiados del dominio.
Reconciliar la Navegación

Actualice anclas, enlaces cruzados y referencias después de cada cambio de encabezado o nombre de archivo.
Validar

Vuelva a ejecutar todas las puertas de calidad y confirme que la revisión no elimine información técnicamente relevante sin una razón explícita.

4.3. Revisión

Cargar Plantilla

Cargue assets/technical-article-template.md antes de revisar un artículo. Úsela como línea base estructural y no informe secciones opcionales omitidas como defectos a menos que su ausencia cree un problema de integridad o coherencia.
Evaluar

Revise el artículo en el siguiente orden:
1. Corrección Técnica
2. Alcance y Coherencia Taxonómica
3. Conformidad Estructural
4. Terminología y Acrónimos
5. Ejemplos, Tablas y Diagramas
6. Enlaces y Referencias
7. Gramática, Puntuación y Legibilidad
Informar Hallazgos

Informe los hallazgos con el encabezado o la línea afectada, el defecto, su consecuencia técnica y una corrección concreta. Priorice los errores fácticos y las inconsistencias estructurales sobre las preferencias de estilo.

5. Guía de Estilo

5.1. Voz y Tono

Tiempo Presente

Use tiempo presente para definiciones, capacidades y prácticas actuales.
Tiempo Pasado

Use tiempo pasado solo para eventos históricos o comportamiento obsoleto.
Voz Activa

Prefiera voz activa cuando el actor o mecanismo sea importante.
Voz Pasiva

Use voz pasiva cuando el proceso o resultado sea el foco y el actor sea irrelevante.
Perspectiva Impersonal

Evite pronombres en primera y segunda persona.
Profesional

Mantenga un tono profesional y objetivo en todo momento.

5.2. Terminología

Específica del Dominio

Use términos técnicos precisos en lugar de palabras genéricas. Por ejemplo, use "despliegue canario" en lugar de "lanzamiento gradual".
Consistente

Mantenga el mismo término para el mismo concepto en todo el artículo.
Definida

Defina términos especializados en su primer uso.
Sin Jerga

Evite jerga, coloquialismos y lenguaje excesivamente informal.
Estándar

Siga la terminología de la industria y los organismos de estandarización cuando esté disponible.

5.3. Oraciones y Párrafos

Longitud de Oración

Varíe la longitud de las oraciones, pero evite oraciones excesivamente largas. Divida oraciones complejas en oraciones más cortas y claras.
Estructura del Párrafo

Cada párrafo debe centrarse en una idea principal. Utilice oraciones temáticas para comenzar los párrafos.
Transiciones

Utilice palabras y frases de transición para conectar ideas dentro y entre párrafos.
Claridad

Priorice la claridad sobre la elegancia. Una comunicación técnica clara es más importante que un estilo literario.
Concisión

Elimine palabras superfluas. Cada palabra debe contribuir al significado.

5.4. Listas y Citas en Bloque

Listas Ordenadas

Use listas ordenadas para secuencias, pasos o elementos clasificados.
Listas No Ordenadas

Use listas no ordenadas para elementos, categorías o características.
Consistencia

Use el mismo tipo de lista para contenido similar. No mezcle listas ordenadas y no ordenadas para elementos paralelos.
Citas en Bloque

Use citas en bloque para definiciones de términos, ejemplos extensos o texto citado. No use citas en bloque para resaltar contenido que no sea una definición o cita.
Viñetas Paralelas

Mantenga las viñetas paralelas en estructura gramatical. Comience con la misma parte de la oración si es posible.

5.5. Enlaces y Citas

Enlaces Descriptivos

Use texto de enlace descriptivo que indique el contenido del destino. Evite "haga clic aquí" o "lea más".
Citas en el Texto

Use citas en el texto con números o etiquetas entre paréntesis cuando se requiera una referencia rápida dentro de la prosa.
Referencias al Final

Proporcione referencias completas en una sección dedicada al final del artículo.
Consistencia del Formato

Mantenga un formato consistente para todos los enlaces y citas.
Verificación de Enlaces

Verifique que todos los enlaces estén activos y apunten al destino previsto.

5.6. Código, Tablas y Advertencias

Bloques de Código

Use bloques de código delimitados para ejemplos de código, comandos y fragmentos de configuración. Especifique el lenguaje para el resaltado de sintaxis.
Código en Línea

Use código en línea para nombres de archivos, nombres de funciones, variables y fragmentos de código cortos.
Tablas

Use tablas para datos tabulares. Mantenga las tablas simples y evite celdas fusionadas cuando sea posible.
Advertencias

Use advertencias de GitHub con moderación. La sintaxis es > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING] o > [!CAUTION].
Diagramas

Use diagramas Mermaid para relaciones y flujos complejos cuando sea apropiado.

6. Puertas de Calidad

Antes de dar por terminado un artículo, verifique cada uno de los siguientes:

Corrección Técnica
- ¿Están todos los hechos verificados contra fuentes autorizadas?
- ¿Son técnicamente plausibles todos los ejemplos?
- ¿No hay afirmaciones falsas o engañosas?
Integridad Estructural
- ¿Hay exactamente un encabezado H1?
- ¿Están todos los encabezados numerados correctamente?
- ¿La tabla de contenido refleja todos los encabezados?
- ¿Se mantienen los anclas correctamente?
Calidad del Lenguaje
- ¿El lenguaje es formal y profesional?
- ¿Se evitan la primera y segunda persona?
- ¿Son las oraciones claras y concisas?
- ¿La terminología es consistente en todo el artículo?
Ejemplos y Datos
- ¿Los ejemplos son relevantes y correctos?
- ¿Las tablas tienen datos precisos y están formateadas correctamente?
- ¿Los bloques de código tienen el identificador de lenguaje correcto?
Referencias
- ¿Todas las referencias externas tienen el tipo de fuente identificado?
- ¿Los enlaces internos son rutas relativas?
- ¿Hay enlaces rotos?
Formato
- ¿La estructura Markdown es válida?
- ¿Se utilizan las advertencias correctamente?
- ¿El formato de la tabla de contenido es correcto?
Legibilidad
- ¿El artículo está bien estructurado?
- ¿Las transiciones entre secciones son suaves?
- ¿El artículo se puede entender sin conocimientos previos del tema?

7. Recursos

assets/technical-article-template.md — Plantilla para crear nuevos artículos.
assets/technical-article-checklist.md — Lista de verificación para puertas de calidad.
Ejemplos en content/articles/ — Artículos de muestra que demuestran la estructura y el estilo.

8. Referencias

Sentenz Guía de Estilo artículo.
Sentenz Taxonomía artículo.
Documentación GitHub Markdown documentación.
Especificación Mermaid Documentación documentación.

sentenz/technical-article

¿Qué es technical-article?

Preguntar en tu IA favorita

Documentación