Un nuevo sistema de comentarios viene a docs.microsoft.com
Este post fue escrito por Rob Eisenberg, Gerente senior del programa en el equipo de docs.microsoft.com.
La misión de Microsoft es capacitar a todas las personas y a todas las organizaciones del planeta para lograr más. Esta fue una de nuestras consideraciones a medida que compilamos docs.microsoft.com sobre la plataforma abierta de GitHub. Hoy, lo estamos llevando al siguiente nivel con el traslado a un nuevo sistema de comentarios de documentación basado en GitHub.
Comentarios de contenido en GitHub
Aunque nuestra documentación ha estado en GitHub desde el principio, nuestro mecanismo de comentarios de contenido ha estado usando Livefyre para comentarios sobre artículos. Aunque Livefyre es una excelente solución de comentarios, resultó ser insuficiente para nuestras necesidades específicas, que es realizar un seguimiento, asignar propietarios y mantener el estado de los problemas de contenido generados por los clientes.
Hemos explorado una serie de vías para mejorarla, pero una pregunta que ha guiado gran parte de nuestro trabajo parecía volver a aparecer: Si nuestra documentación se tratara como código fuente abierto, ¿qué usaríamos para resolver este problema? La respuesta a la pregunta parecía obvia: problemas de GitHub, por lo que empezamos a experimentar con la integración de las API de GitHub más profundamente en nuestras páginas de documentación, pudiendo crear un sistema de comentarios completo sobre la infraestructura de GitHub.
Con el nuevo sistema, ahora puede crear problemas de GitHub directamente desde una página de contenido, lo que le permite interactuar de forma mucho más rica con escritores y equipos de productos. ¿Ve un problema con un documento? ¿Un ejemplo de código incorrecto? ¿Una explicación confusa? ¿Una omisión crítica? Simplemente desplácese hasta la parte inferior de la página y seleccione Enviar comentarios de documentación.
Puede ver todos los problemas abiertos y cerrados asociados con el documento, directamente desde la propia página de documentación, de esa manera que siempre está en conocimiento cuando se corrigen y resuelven las cosas:
Puede comentar e incluso agregar reacciones a los problemas que son importantes para usted:
Ahora, los empleados de Microsoft pueden aprovechar toda la eficacia de los problemas de GitHub para evaluar, responder, planear y corregir problemas notificados, y siempre tendrá visibilidad del proceso.
Comentarios de documentación de ejemplo
Supongamos que archiva un problema de GitHub para un hipervínculo roto en un artículo. Nuestro equipo evaluará el problema, asignará una etiqueta y asignará un propietario para realizar la corrección (o formular preguntas de seguimiento). Cuando el propietario envíe una solicitud de incorporación de cambios que corrija el problema, se le notificará (en función de la configuración de notificación de GitHub), que el problema se ha resuelto o cerrado, creando un ciclo virtuoso de comentarios.
Además, puede aprovechar todas las ventajas estándar de GitHub, como Markdown en comentarios, suscripciones a problemas individuales o repositorios completos, fuentes RSS de actividad de la organización, @ menciones, asignadores y mucho más. Creemos que el nivel más profundo de integración de herramientas de código abierto va a fomentar nuevas oportunidades para el crecimiento y la colaboración de la comunidad.
Separación de comentarios de productos
Uno de los problemas con el sistema anterior era la combinación entre los comentarios del producto y la documentación en una secuencia: era extremadamente difícil evaluar y realizar un seguimiento, cuando no todos los elementos se etiquetan de forma coherente. Hemos seguido un paso adelante para solucionar este problema mediante la creación de una manera clara de separar las dos:
Al hacer clic en Enviar comentarios sobre el producto, ahora se le llevará directamente al sitio donde el equipo de productos asociado a la página de documentación específica controla los comentarios del producto.
Roll-Out
Es posible que se pregunte cuándo estará activo el sistema de comentarios. Hace un par de meses que lo hemos piloto para la del IDE de Visual Studio de y la documentación de la CLI de Azure . A partir de mediados de febrero, comenzaremos a implementar esto en todos los docs.microsoft.com.
Sus comentarios
Sus comentarios son importantes para nosotros, por lo que queremos poner este nuevo sistema en sus manos rápidamente. Aunque es nuestro siguiente paso para mejorar los comentarios y la participación en nuestra plataforma, no es por ningún medio nuestro último paso. Asegúrese de expresar sus pensamientos sobre los cambios en GitHubo etiquetenos en Twitter.