Se incorpora un nuevo sistema de comentarios a docs.microsoft.com
Esta entrada la ha escrito Rob Eisenberg, director de programas del equipo de docs.microsoft.com.
El objetivo de Microsoft es permitir que todas las personas y organizaciones puedan lograr muchas más cosas. Este fue uno de los factores que tuvimos en cuenta al crear docs.microsoft.com sobre la plataforma abierta de GitHub. Hoy pasamos a otro nivel con la incorporación de un nuevo sistema de comentarios sobre documentación basado en GitHub.
Comentarios sobre el contenido en GitHub
Nuestra documentación siempre ha estado en GitHub, pero, para los artículos, el mecanismo para enviar comentarios sobre el contenido utilizaba Livefyre. A pesar de que Livefyre es una solución genial para enviar comentarios, no ha logrado satisfacer nuestras necesidades particulares: el seguimiento, la asignación de propietarios y el mantenimiento del estado de los problemas de contenido que detectan los clientes.
Hemos hecho todo lo posible para mejorarlo, pero una de las preguntas clave de nuestro trabajo parecía no tener respuesta: si tratáramos nuestra documentación como código fuente abierto, ¿qué usaríamos para resolver el problema? La respuesta a la pregunta parecía evidente: los problemas de GitHub, así que empezamos a experimentar con la integración de las API de GitHub en nuestras páginas de documentación con mayor profundidad, cosa que nos permitió crear un sistema de comentarios completo sobre la infraestructura de GitHub.
Con el nuevo sistema, ahora es posible crear problemas de GitHub directamente en una página de contenido, lo cual permite interactuar de una forma mucho más completa con los equipos de redacción y producto. ¿Ha detectado un problema en un documento? ¿Un ejemplo de código incorrecto? ¿Una explicación confusa? ¿Una omisión de contenido grave? Solo tiene que desplazarse hasta el final de la página y seleccionar Comentarios sobre el contenido.
Puede consultar todos los problemas abiertos y cerrados asociados a un documento directamente en la página de documentación en cuestión. De este modo, siempre estará al corriente del momento en el que los errores se corrijan y resuelvan:
Puede escribir comentarios en los problemas que le parezcan importantes, e incluso agregar reacciones:
Ahora, los empleados de Microsoft pueden aprovechar todo el potencial de los problemas de GitHub para evaluar la prioridad de los problemas notificados, establecer una planeación, corregirlos y responder a ellos, todo con total transparencia sobre el proceso.
Ejemplo de comentarios sobre la documentación
Supongamos que registra un problema de GitHub referente a un hipervínculo roto en un artículo. Nuestro equipo evaluará la prioridad y le asignará una etiqueta y un propietario para corregirlo, o bien para efectuar las preguntas de seguimiento pertinentes. Cuando el propietario envíe una solicitud de incorporación de cambios para corregir el problema, recibirá una notificación (según la configuración que tenga establecida para las notificaciones de GitHub) en la que se indicará que el problema se ha corregido o cerrado, cosa que dará paso a un ciclo de comentarios muy positivo.
Además, puede aprovechar todas las ventajas estándar de GitHub, como las marcas de los comentarios, las suscripciones a problemas concretos o repositorios enteros, las fuentes RSS de actividad de la organización, las menciones con el símbolo @, los usuarios asignados y mucho más. Creemos que, con un mayor nivel de integración con las herramientas de código abierto, surgirán nuevas oportunidades para la colaboración y el crecimiento de la comunidad.
Separación de los comentarios sobre el producto
Uno de los problemas del sistema anterior era que los comentarios sobre el producto y la documentación estaban mezclados en un único flujo, es decir, no todos los elementos se etiquetaban de forma coherente, cosa que dificultaba muchísimo la evaluación de prioridades y el seguimiento. Para solucionar este problema, hemos ido más allá y hemos creado un método muy claro para separarlos:
Ahora, al hacer clic en Comentarios sobre el producto, se le redirigirá directamente al sitio web en el que el equipo de producto asociado a la página de documentación específica administra los comentarios sobre el producto.
Implementación
Tal vez se esté preguntando cuándo implementaremos este sistema de comentarios. Durante los últimos meses hemos estado llevando a cabo toda una serie de pruebas piloto con la documentación de CLI de Azure y el IDE de Visual Studio. A partir de mediados de febrero empezaremos a implementarlo en toda la infraestructura de docs.microsoft.com.
Comentarios de los usuarios
Sus comentarios son muy importantes para nosotros, así que nuestra intención es que disponga de este nuevo sistema a la mayor brevedad. Aunque este será el siguiente paso para mejorar los comentarios y la interacción en nuestra plataforma, conviene destacar que en ningún caso será el último. No olvide exponer su opinión sobre los cambios en GitHub y recuerde que también puede etiquetarnos en Twitter.