Usa secciones de solución de problemas en las guías o los artículos de procedimientos para mantener las soluciones cerca de los procedimientos. Trabaja con el equipo de soporte técnico y los directores de productos para poner de relieve errores comunes e incluirlos en la documentación.
Problemas conocidos
Los problemas conocidos son un subconjunto de contenido de solución de problemas diseñado específicamente para responder a errores, problemas de la interfaz o la experiencia del usuario, y otras anomalías en los productos que generan un gran volumen de incidencias de soporte técnico. Mientras el contenido de solución de problemas describe errores que los usuarios podrían encontrar, los problemas conocidos explican los problemas que encontrarán los usuarios.
Al igual que todo el contenido de solución de problemas, los problemas conocidos pueden ser una sección dentro de un artículo o un artículo aparte. Si un problema conocido se aplica a un artículo específico, documéntelo en ese artículo. Si un problema conocido se aplica a un conjunto de artículos específico o a un grupo conceptual de características concreto, o si un producto o una característica tiene varios problemas conocidos que deberían agruparse, cree un artículo dedicado de tipo "Known issues with NOMBRE".
No es necesario que el contenido del problema conocido de un producto o una característica esté completo. A diferencia de otro contenido de solución de problemas, es posible que algunos problemas conocidos no tengan soluciones alternativas. El objetivo de documentar un problema sin una solución alternativa es ayudar a los usuarios a confirmar que el problema existe y ahorrarles el tiempo de buscar una solución que aún no existe una vez que GitHub ya ha determinado que no hay ninguna solución alternativa.
Los propietarios de productos y características (PM y EM) deben ayudar a planear y revisar el contenido de problemas conocidos.
Usa problemas conocidos para explicar las siguientes situaciones.
- Comportamiento del producto que contradice a menudo las expectativas de los usuarios, pero que aún no se ha priorizado para corregirlo.
- Comportamiento que con frecuencia impide el uso del producto o la característica para una finalidad común.
- Errores poco frecuentes o graves que GitHub aún no ha priorizado para corregirlos y que no se explican en el producto ni en el contenido actual de GitHub Docs.
Cómo escribir contenido de solución de problemas
- Usa cualquier tipo de contenido de GitHub Docs para crear secciones de solución de problemas.
- Siempre que sea posible, mantén el contenido de solución de problemas dentro de contenido de procedimientos o guías.
- Puedes crear un artículo de solución de problemas cuando tenga sentido ponerlo aparte; por ejemplo, cuando hay una gran cantidad de contenido de solución de problemas sobre un tema determinado.
- Puedes crear un tema relacionado de solución de problemas si un producto o característica tiene muchos artículos de solución de problemas; por ejemplo, "Solucionar problemas de SSH".
Directrices para el título del contenido de solución de problemas
- Troubleshooting CARACTERÍSTICA
- Error: NOMBRE DEL ERROR
- Known issues for PRODUCTO
Ejemplos de contenido de solución de problemas
- "Solucionar problemas de SSH"
- "Utilizar el servidor de GitHub Enterprise con un balanceador de carga"
- "Known issues" en las notas de la versión de GitHub Enterprise Server
- "Error: Estamos haciendo una auditoría de clave SSH"