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 tiempo en buscar una solución que aún no existe después GitHub de que ya haya 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 han priorizado la corrección y que no se explican en el producto o por el contenido existente en GitHub Docs.
Cómo escribir contenido de solución de problemas
- Use cualquier GitHub Docs tipo de contenido 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.
- Puede 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
- Problemas conocidos para PRODUCTO
Ejemplos de contenido de solución de problemas
- Solucionar problemas de SSH
- Uso de GitHub Enterprise Server con un equilibrador de carga
- Problemas conocidos en las notas de la GitHub Enterprise Server versión
- Error: Estamos haciendo una auditoría de clave SSH