Guía para colaboradores de Microsoft Docs: información general
Le damos la bienvenida a la guía para colaboradores docs.microsoft.com (Docs).
Varios de los conjuntos de documentación de Microsoft son de código abierto y se hospedan en GitHub. No todos los conjuntos de documentos son completamente de código abierto, pero muchos tienen repositorios públicos en los que puede realizar cambios sugeridos mediante solicitudes de incorporación de cambios. Este enfoque de código abierto optimiza y mejora la comunicación entre los ingenieros de productos, los equipos de contenido y los clientes, y tiene otras ventajas:
- Los repositorios de código abierto se planean a la vista para obtener comentarios sobre qué documentos son más necesarios.
- Los repositorios de código abierto se revisan a la vista para publicar el contenido más útil en la primera versión.
- Los repositorios de código abierto se actualizan a la vista para facilitar la mejora continua del contenido.
La experiencia del usuario de docs.microsoft.com integra directamente flujos de trabajo de GitHub para que resulte todavía más fácil. Para comenzar, edite el documento que está viendo. También puede revisar nuevos temas o notificar problemas de calidad.
Importante
Todos los repositorios que publican en docs.microsoft.com han adoptado el Código de conducta de código abierto de Microsoft o el Código de conducta de .NET Foundation. Para obtener más información, vea las preguntas más frecuentes del Código de conducta. O bien póngase en contacto con opencode@microsoft.com o conduct@dotnetfoundation.org para enviar sus preguntas o comentarios.
Las correcciones menores o aclaraciones de la documentación y los ejemplos de código de los repositorios públicos se rigen por los Términos de uso del sitio docs.microsoft.com. Los cambios importantes o nuevos generan un comentario en la solicitud de incorporación de cambios que le pide que acepte el contrato de licencia de colaboración (CLA) si no es un empleado de Microsoft. Necesitamos que rellene el formulario en línea para revisar o aceptar su solicitud de incorporación de cambios.
Ediciones rápidas en documentos existentes
Las ediciones rápidas optimizan el proceso de notificación y corrección de pequeños errores y omisiones en los documentos. A pesar de todos los esfuerzos, en ocasiones los documentos que publicamos contienen algunos errores gramaticales y erratas. Aunque puede notificar un problema para informar sobre estos errores, es más rápido y fácil crear una solicitud de incorporación de cambios para corregirlo, cuando la opción esté disponible.
Algunas páginas de documentos permiten editar contenido directamente en el explorador. En este caso, verá un botón Editar, como el que se muestra a continuación. Al hacer clic en el botón Editar, se le redirige al archivo de código fuente en GitHub. Si falta el botón Editar, significa que la página de documentación no se puede modificar.
Si el botón Editar no aparece, el contenido no está abierto para las contribuciones públicas.
Seleccione el icono de lápiz para editar el archivo. Si el icono de lápiz aparece atenuado, debe iniciar sesión en su cuenta de GitHub, o bien crear una.
Haga los cambios necesarios en el editor web. Haga clic en la pestaña Preview changes (Vista previa de los cambios) para comprobar el formato del cambio.
Una vez que haya realizado los cambios, desplácese hasta la parte inferior de la página. Escriba un título y una descripción para los cambios y haga clic en Propose file change (Proponer cambio en archivo), como se muestra en la ilustración siguiente:
Ahora que ha propuesto el cambio, es necesario solicitar a los propietarios del repositorio que "inserten" los cambios en su repositorio. Para ello, se usa algo denominado "solicitud de incorporación de cambios". Cuando seleccione Propose file change (Proponer cambio en archivo), se mostrará una nueva página parecida a esta:
Seleccione Crear solicitud de incorporación de cambios escriba un título y, si quiere, una descripción para dicha solicitud. A continuación, seleccione de nuevo Crear solicitud de incorporación de cambios. Si acaba de empezar a usar GitHub, consulte Acerca de las solicitudes de extracción para obtener más información.
Eso es todo. Los miembros del equipo de contenido revisarán y combinarán la solicitud una vez que se haya aprobado. Puede que reciba comentarios en los que se le soliciten cambios.
La interfaz de usuario de edición de GitHub responde a sus permisos en el repositorio. Las imágenes anteriores hacen referencia a colaboradores que no tienen permisos de escritura en el repositorio de destino. GitHub crea automáticamente una bifurcación del repositorio de destino en su cuenta. Si tiene acceso de escritura al repositorio de destino, GitHub crea en él una rama. El nombre de la rama tiene el formato GitHubId>-patch-n, en el que se usa su identificador de GitHub y un identificador numérico para la rama de la revisión.
Usamos solicitudes de incorporación de cambios con todos los cambios, incluso con los colaboradores que tienen acceso de escritura. La mayoría de los repositorios tienen la rama predeterminada protegida para que las actualizaciones se tengan que enviar como solicitudes de incorporación de cambios.
La experiencia de edición en el explorador es mejor para los cambios menores o poco frecuentes. Si realiza grandes colaboraciones o usa características avanzadas de Git (como la administración de ramas o la resolución avanzada de conflictos de fusión), debe bifurcar el repositorio y trabajar localmente.
Nota
La mayoría de la documentación localizada no ofrece la posibilidad de editarse ni de proporcionar comentarios mediante GitHub. Para proporcionar comentarios sobre el contenido localizado, use la plantilla de correo electrónico disponible en aka.ms/DocSiteLocFeedback. Hay una excepción para la documentación de Azure. Existen repositorios de GitHub localizados públicos para azure-docs que están abiertos a la contribución de la comunidad en seis idiomas: chino simplificado, francés, alemán, japonés, coreano y español. Para todos los demás idiomas y conjuntos de contenido, use la plantilla de correo electrónico (que admite comentarios en cualquier idioma) para notificar problemas de traducción o para proporcionar comentarios técnicos.
Revisión de solicitudes de incorporación de cambios abiertas
Para leer nuevos temas antes de que se publiquen, consulte las solicitudes de incorporación de cambios abiertas. Las revisiones siguen el proceso del flujo de GitHub. Puede ver las actualizaciones propuestas o artículos nuevos en los repositorios públicos. Revíselos y agregue sus comentarios. Examine cualquiera de nuestros repositorios de documentos y consulte las solicitudes de incorporación de cambios abiertas para las áreas que le interesen. Los comentarios de la comunidad sobre las actualizaciones propuestas ayudan al conjunto de la comunidad.
Notificación de problemas de calidad
Nuestros documentos son siempre un trabajo en curso. Los problemas positivos nos ayudan a centrar nuestros esfuerzos en las prioridades de la comunidad. Cuantos más detalles aporte, más útil será el problema notificado. Díganos qué información buscaba. O enumere los términos de búsqueda que empleó. Si no puede comenzar, coméntenos cómo le gustaría empezar a explorar una tecnología desconocida.
Muchas de las páginas de documentación de Microsoft tienen una sección Comentarios en la parte inferior donde puede hacer clic para dejar sus Comentarios sobre el producto o Comentarios sobre el contenido y así realizar el seguimiento de problemas que son específicos de ese artículo.
Los problemas ayudan a iniciar una conversación sobre lo que hace falta. El equipo de contenido responderá a estos problemas con ideas sobre lo que se puede agregar y le pedirá su opinión. Cuando creemos un borrador, le pediremos que revise la solicitud de incorporación de cambios.
Mayor implicación
Otros temas le ayudarán a empezar a colaborar de manera productiva en Microsoft Docs. En ellos se explica cómo trabajar con repositorios de GitHub, herramientas de Markdown y extensiones usadas en la plataforma de Microsoft Docs.