Artículos de documentación: Referencia versionada para usuarios existentes

Un artículo de documentación es una referencia mantenida para alguien que ya utiliza un producto, API, servicio, dispositivo o proceso operativo. Responde una pregunta de consulta precisa —qué hace un ajuste, qué valores acepta un campo, qué acceso se requiere, qué versión se comporta de esta manera, o dónde se aplica un límite— sin obligar al lector a pasar primero por un argumento de marketing.

Su contrato es alcance → requisitos previos → comportamiento actual → referencia exacta → excepciones → tarea relacionada. La página tiene éxito cuando un usuario obtiene el dato correcto para la versión y el rol adecuados. Convertir cada etiqueta de interfaz en una URL pública no ayuda.

Preguntas que responde

La pregunta principal es: "¿Qué significa este comportamiento del producto en mi versión y contexto?" Las preguntas de apoyo incluyen:

• ¿Esta página aplica a mi producto, plan, rol, región, plataforma y versión?
• ¿Qué debe ser cierto antes de que pueda usar esta función o consultar este campo?
• ¿Cuáles son los valores aceptados, valores predeterminados, límites, formatos y efectos secundarios?
• ¿Qué comportamiento es actual y qué cambió respecto a una versión anterior?
• ¿Qué ejemplo demuestra la regla sin ocultar condiciones importantes?
• ¿Qué debería leer a continuación si necesito un procedimiento, diagnóstico o historial de cambios?
• ¿Esta información es segura y útil en la búsqueda pública, o requiere contexto autenticado?

Cuándo usar este tipo de publicación

Usa documentación cuando una página estable deba soportar consultas repetidas. El tema necesita un propietario autorizado, un comportamiento comprobable y una señal de mantenimiento como un lanzamiento, API, plan o cambio de interfaz.

Una página llamada “Cómo configurar los campos de exportación” puede seguir siendo documentación cuando su valor duradero es un catálogo de campos y los usuarios saltan directamente a parámetros individuales. Por el contrario, “Exporta tu primer informe” es una guía práctica cuando el lector debe seguir una secuencia y verificar un archivo descargado. La gramática del título no decide el formato; la tarea del lector y la forma de la respuesta sí lo hacen.

Mejor para estos tipos de negocio

1. SaaS. El mejor ajuste porque los roles, planes, configuraciones, integraciones, APIs, modelos de datos y cadencia de lanzamiento producen necesidades de referencia exactas. La documentación debe distinguir el comportamiento de la interfaz del comportamiento de la API y los permisos de usuario de las prestaciones de la suscripción.
2. Ecommerce. Ideal para administración de comerciantes, feeds de productos, reglas de pago, devoluciones, integraciones y uso post-compra. Separa la ayuda al cliente de la documentación del comerciante para que un comprador no termine en una referencia de implementación.
3. Marketplaces. Útil donde los roles de comprador, vendedor, proveedor y administrador ven estados diferentes. Cada artículo debe identificar al actor porque la misma etiqueta puede exponer diferentes controles u obligaciones.
4. Agencias. Útil para portales de clientes, estándares de entregables, flujos de trabajo recurrentes y herramientas compartidas. Publica referencias reutilizables para clientes solo cuando no expongan controles internos, credenciales o detalles operativos propietarios.
5. Servicios B2B. Útil para sistemas de incorporación, transferencias de datos, especificaciones de archivos, estados de aprobación y portales de servicio. Evita presentar un compromiso contractual como un hecho genérico de centro de ayuda cuando los términos varían según la cuenta.
6. Fabricantes y empresas industriales. Valioso para controles, software, compatibilidad, configuración, registros de mantenimiento y parámetros técnicos. El material crítico para la seguridad requiere revisión controlada, aplicabilidad explícita del modelo y una ruta al manual autorizado.

Intención de búsqueda

La intención de búsqueda es el resultado que una persona espera de una consulta. La intención en la documentación suele ser navegacional más informacional: el buscador conoce el producto u objeto y quiere un dato exacto, como “retención de exportaciones de Northstar”, “valores de estado de Northstar” o “tamaño de página de la API de Northstar”. La marca, función, lenguaje de tarea sin errores, versión y plataforma suelen aparecer juntos.

El resultado ideal abre cerca de la respuesta. Usa encabezados descriptivos, anclajes estables, valores aceptados y calificadores de versión. Una declaración extraída debe preservar su condición: “En los planes Team y Enterprise, las exportaciones completadas permanecen disponibles durante 30 días.”

La documentación pública debe posicionarse cuando responde una pregunta duradera sin revelar datos de cuenta: formatos compatibles, campos de API públicos, compatibilidad, límites, significado de configuración y comportamiento documentado.

La documentación no debe posicionarse cuando refleja una etiqueta de interfaz, duplica una página actual, cubre una versión obsoleta sin necesidad continua, expone detalles sensibles o necesita contexto de cuenta privada. Usa en su lugar ayuda autenticada, guía en la aplicación, noindex, consolidación o un estado de archivo claro. La demanda de búsqueda nunca justifica publicar secretos o rutas de explotación.

Estructura de la página

Las bandas de palabras son controles de producción, no cuotas mínimas. Una referencia de campo reducido puede ser más corta; una referencia de funcionalidad versionada puede necesitar más espacio porque la aplicabilidad y las excepciones evitan errores costosos.

La mayoría de los artículos de documentación sustanciales tienen entre 1500 y 2800 palabras. Añade detalle solo donde evite ambigüedad: alcance, requisito previo, valor, valor predeterminado, efecto secundario, excepción o cambio de versión.

Elementos requeridos

Los lectores de referencia escanean. Posiciona la información de aplicabilidad antes de la referencia para que un valor técnicamente correcto no se aplique al plan o lanzamiento equivocado.

Frontmatter

Sigue la especificación de frontmatter. En esta especificación de tipo de publicación, entity = "post-type-documentation-article". En una página de documentación producida, usa un valor de objeto-producto estable como northstar-scheduled-export-settings, no una frase promocional como effortless-reporting ni un número de versión que forzaría una nueva identidad después de cada lanzamiento.

Usa schemaType = "Article". El marcado de schema debe describir la página visible; no selecciones HowTo simplemente porque un ejemplo contiene tres acciones. Añade datos estructurados FAQ solo cuando las preguntas y respuestas visibles coincidan exactamente con ellos. La referencia de API o la semántica específica de software pueden representarse en otro lugar del modelo de datos del sitio, pero no debe inventarse un tipo de schema más específico en el frontmatter sin soporte de plantilla.

Almacena los campos que el sistema de mantenimiento puede gestionar: área de producto, planes, rol, plataforma, rango de versiones, fecha de verificación, propietario y URL de reemplazo. lastmod significa que el comportamiento fue revisado, no que se corrigió un error tipográfico. Preserva la URL canónica entre lanzamientos compatibles.

Ejemplo completo

Este ejemplo ficticio de analítica demuestra una página de referencia, no un procedimiento de exportación completo.

# Configuración de exportaciones programadas

Las exportaciones programadas crean un archivo CSV o JSON a partir de un informe guardado en una hora UTC fija y lo entregan a un destino aprobado. Están disponibles para Editores y Administradores en los planes Team y Enterprise. Esta referencia aplica a la aplicación web Northstar Analytics 6.4 y fue verificada el 27 de agosto de 2026.

## Antes de usar esta referencia

Necesitas un informe guardado existente, un destino habilitado y acceso de Editor o Administrador. Un Visor puede descargar una exportación existente pero no puede crear ni modificar una programación. Los administradores del destino pueden imponer límites adicionales de retención o tamaño de archivo.

## Referencia de configuración

| Configuración | Valor aceptado | Predeterminado | Efecto y restricciones |
|---|---|---|---|
| Nombre | 1–80 caracteres | Nombre del informe | Identifica la programación; cambiarlo no renombra archivos anteriores. |
| Formato | `csv` o `json` | `csv` | CSV usa el orden de columnas visible del informe. JSON usa claves de campo estables. |
| Hora de ejecución | `HH:MM` en UTC | `08:00` | Los cambios de horario de verano no modifican la hora UTC de ejecución. |
| Incluir filas vacías | Activado o desactivado | Desactivado | Disponible solo para informes tabulares; ignorado para informes resumidos. |
| Retención | 1–30 días | 7 días | Los archivos existentes caducan independientemente de la programación que los creó. |

## Comportamiento y límites

Una programación lee la configuración del informe guardado cuando comienza la ejecución. Por lo tanto, editar el informe cambia los archivos futuros pero no los ya generados. Pausar una programación evita nuevas ejecuciones; no elimina los archivos retenidos. Eliminar el destino desactiva la entrega y coloca la programación en «Necesita atención».

## Ejemplo

Para un CSV diario necesario a las 09:00 en Bratislava durante la hora estándar, establece la hora UTC de ejecución en `08:00`. Revisa la hora cuando cambien las reglas de horario de verano porque las programaciones permanecen fijas en UTC.

Ejemplo inválido: introducir `Europe/Bratislava` en el campo de hora de ejecución. El campo acepta una hora UTC, no un identificador de zona horaria.

## Diferencias entre versiones

- Versión 6.4: Las exportaciones JSON usan claves de campo estables; la etiqueta de columna mostrada ya no se convierte en la clave.
- Versiones 6.1–6.3: Las claves JSON siguen las etiquetas de columna mostradas. Las integraciones existentes deben verificarse antes de la actualización.
- Antes de 6.1: la exportación JSON programada no está disponible. Usa CSV o actualiza a una versión compatible.

## Si una exportación no llega

No añadas soluciones especulativas aquí. Abre la guía de solución de problemas «La exportación programada no llegó», que verifica el estado de la programación, la autorización del destino, los límites de archivos y los incidentes del servicio en orden de diagnóstico.

## Tareas relacionadas

- Crea tu primera exportación programada — configuración ordenada y verificación de éxito
- Soluciona problemas de una exportación programada faltante — diagnóstico basado en síntomas
- Notas de la versión de Northstar Analytics 6.4 — cambios de comportamiento y nota de migración

## Registro de verificación

Verificado contra la aplicación web 6.4 por el propietario del producto de Informes el 27 de agosto de 2026. Revisar cuando cambien los permisos, formatos, retención, programación o comportamiento del destino.

Galería de diseño

Usa configuraciones, límites, roles y datos de versión idénticos entre variantes para que la revisión de diseño mida la velocidad de recuperación en lugar de las diferencias de texto.

Lista de verificación de calidad

Un artículo de documentación está listo solo cuando cada afirmación aplicable es verdadera:

• La apertura nombra el objeto exacto y proporciona el comportamiento actual antes que el contexto o los beneficios.
• La aplicabilidad de producto, plan, rol, región, plataforma y versión es explícita donde cambian la respuesta.
• Los requisitos previos aparecen antes que las configuraciones o ejemplos que dependen de ellos.
• Cada término técnico se define en su primer uso, se expresa mediante una etiqueta de interfaz familiar o se enlaza a su definición canónica.
• Los campos, valores, valores predeterminados, unidades, formatos, límites y efectos secundarios provienen de una fuente autorizada o de una prueba de producto verificada.
• Las tablas de referencia usan dimensiones coherentes; las celdas vacías no ocultan valores predeterminados o excepciones desconocidos.
• Los ejemplos indican las condiciones que los hacen válidos e incluyen un ejemplo inválido o límite cuando es probable que haya confusión.
• Las advertencias aparecen antes de comportamientos destructivos, irreversibles, sensibles a la seguridad, costosos o que modifican permisos.
• Las capturas de pantalla incluyen una versión de captura y un equivalente de texto; la imagen no es la única fuente de un valor o instrucción.
• Los encabezados y anclajes coinciden con los sustantivos que los usuarios buscan y permanecen estables para enlaces profundos.
• Las diferencias materiales entre versiones indican el rango afectado, el reemplazo actual y la consecuencia de migración.
• La fecha de verificación refleja una revisión de comportamiento, y un equipo o rol nombrado es responsable de la próxima revisión.
• Los procedimientos, diagnósticos e historial de lanzamientos enlazan a páginas hermanas canónicas en lugar de duplicarse de forma incompleta.
• La indexación pública es intencional; el material obsoleto, duplicado, privado y sensible a la seguridad tiene un tratamiento de búsqueda adecuado.
• Los registros FAQ coinciden con las respuestas visibles, y el CTA respeta la siguiente tarea del lector en etapa de soporte.

Errores comunes

Escribir una página de aterrizaje de funcionalidad para un usuario existente. «Desbloquea exportaciones potentes» retrasa el dato que el lector necesita. Empieza con comportamiento, aplicabilidad y restricciones; el texto de beneficios pertenece solo donde aclara el propósito.

Convertir cada tarea en documentación. Una configuración de 20 pasos enterrada debajo de una lista de campos no sirve ni para consulta ni para finalización. Divide el procedimiento ordenado en una guía práctica y enlázalo desde el requisito previo o la sección de tareas relacionadas correspondiente.

Publicar una página por etiqueta de interfaz. Las páginas delgadas se superponen y multiplican el mantenimiento. Agrupa los campos alrededor de un objeto de producto estable a menos que una configuración tenga un comportamiento distinto.

Usar «última versión» como versión. La última versión cambia. Indica el lanzamiento probado, el rango compatible, la plataforma y la fecha de verificación, luego actualízalos a través del proceso de lanzamiento.

Mantener páginas antiguas y nuevas indexables sin un límite. Consolida el comportamiento compatible; de lo contrario, etiqueta la versión antigua, enlaza a la página actual y controla la indexación intencionadamente.

Ocultar los requisitos previos dentro de los errores. Si solo los Administradores pueden cambiar un campo, dilo antes de la referencia. No hagas que un Visor descubra el límite del rol después de seguir un ejemplo.

Copiar capturas de pantalla en lugar de comportamiento. Una captura es evidencia de un estado de interfaz, no la especificación. Escribe etiquetas, rutas, valores y condiciones en texto accesible y registra la versión capturada.

Fingir actualización. Cambiar la fecha sin volver a probar el comportamiento hace que la página parezca más segura mientras aumenta el riesgo. Actualiza el registro de verificación solo después de que su propietario verifique las afirmaciones aplicables.

Permitir que la búsqueda pública exponga detalles internos. Las rutas de escalación internas, secretos, identificadores de clientes, instrucciones de explotación y comportamientos no anunciados no se vuelven seguros porque reducen el esfuerzo de soporte. Separa la ayuda pública del conocimiento autenticado e interno.

Enlazado interno

Enlaza hacia arriba a Tipos de publicaciones SEO cuando el autor pueda necesitar una forma de respuesta diferente. Enlaza desde un requisito previo de documentación a la guía práctica canónica solo cuando el lector deba completar esa tarea primero. Enlaza desde un estado de error a la solución de problemas en lugar de insertar una lista de soluciones genérica. Enlaza desde una diferencia de versión al evento de lanzamiento cuando el historial de cambios añada contexto; las notas de la versión deben enlazar de vuelta a la documentación actual como la fuente de verdad duradera.

Organiza los enlaces alrededor de objetos de producto y del estado del lector. Mantén un enlace específico junto a la declaración que crea la siguiente pregunta en lugar de depender de una larga lista de artículos relacionados.

Una página canónica actual debe ser propietaria del comportamiento estable. Mantén las páginas de versión solo para comportamientos materialmente diferentes que los usuarios aún necesiten, y haz explícita esa distinción. Usa anclajes estables como #retention, no #table-2.

Cómo medir los resultados

Mide si los usuarios obtienen la respuesta correcta para su versión. El tráfico por sí solo es una evidencia débil: un aumento puede reflejar un producto roto o una respuesta obsoleta.

Registra las consultas objetivo, la URL de posicionamiento, la indexabilidad, las versiones compatibles, las búsquedas de soporte, las salidas a tareas relacionadas y un evento de producto adecuado. Luego revisa:

• impresiones de búsqueda y visitas cualificadas para consultas de objeto de producto, campo, límite, sintaxis, rol y versión;
• refinamientos de búsqueda interna, búsquedas sin resultados y búsquedas repetidas que revelan terminología faltante;
• interacción con secciones ancladas en lugar de tiempo indiferenciado en la página;
• clics al destino correcto de configuración, solución de problemas, lanzamiento o soporte;
• contactos de soporte cuya pregunta la página debería responder, segmentados por versión y rol cuando la privacidad lo permita;
• citas que preservan el valor junto con su plan, versión, unidad o requisito previo;
• URL obsoletas que aún se posicionan o son citadas después de la consolidación o retirada;
• cambios en la documentación causados por lanzamientos, cambios de interfaz, cambios de política y casos de soporte recurrentes.

Usa el seguimiento de prompts para preguntas de consulta con marca y variantes de versión. Usa la inteligencia de fuentes y citas para ver qué URL cita un motor de respuestas y si su resumen preserva las condiciones. Abre el AmICited Cockpit para comparar URL citadas, visibilidad, actividad de aterrizaje orgánico y el evento de producto o soporte elegido durante la misma ventana de observación.

Sigue cómo medimos los resultados para separar descubrimiento, representación, interacción, progresión de tareas y retención. Anota los lanzamientos e incidentes antes de interpretar movimientos. Una respuesta de clic cero funciona solo cuando preserva el valor actual y sus condiciones.

FAQ

Preguntas frecuentes