Guía para colaboradores de Microsoft Docs: información general

Le damos la bienvenida a la guía de colaboradores de Microsoft 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 sugerir cambios mediante solicitudes de incorporación de cambios (PR). 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 en Microsoft Docs 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 incidencias de calidad.

Importante

Todos los repositorios que publican en Microsoft Docs 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. 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 PR 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 PR.

Ediciones rápidas en la documentación

Las ediciones rápidas optimizan el proceso de notificación y corrección de pequeños errores y omisiones en la documentación. A pesar de todos los esfuerzos, en ocasiones los documentos que publicamos contienen algunos errores gramaticales y erratas. Aunque puede notificar una incidencia para informar sobre estos errores, es más rápido y fácil crear una PR para corregirlo, cuando la opción esté disponible.

  1. 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 elegir el botón Editar, se le redirige al archivo de código fuente en GitHub.

    Ubicación del vínculo para editar el artículo.

    Si el botón Editar no está, significa que el contenido no está abierto a contribuciones públicas. Algunas páginas se generan (por ejemplo, a partir de documentación insertada en el código) y deben editarse en el proyecto al que pertenecen.

  2. 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.

    Ubicación del icono de lápiz para editar y bifurcar.

  3. Edite el archivo en el editor web. Elija la pestaña Vista previa para comprobar el formato de los cambios.

  4. Cuando haya terminado de editarse, desplácese a la parte inferior de la página. En el área Proponer cambios, escriba un título y, opcionalmente, una descripción para los cambios. El título será la primera línea del mensaje de confirmación. Seleccione Proponer cambios para confirmar los cambios:

    Proponer y confirmar los cambios en el archivo.

  5. Ahora que ha propuesto y confirmado los cambios, es necesario solicitar a los propietarios del repositorio que los "inserten" en sus repositorios. Para ello, se usa algo denominado "solicitud de incorporación de cambios" (PR). Cuando seleccione Propose changes (Proponer cambios), se mostrará una nueva página parecida a esta:

    Comparar los cambios y crear solicitudes de incorporación de cambios.

    Seleccione Crear solicitud de incorporación de cambios. Después, escriba un título y una descripción para PR y, a continuación, seleccione Crear solicitud de incorporación de cambios. Si acaba de empezar a usar GitHub, consulte About pull requests (Acerca de las solicitudes de incorporación de cambios) para obtener más información.

  6. Eso es todo. Los miembros del equipo de contenido revisarán la PR y la combinarán 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. El nombre de bifurcación recién creado tiene el formulario GitHubUsername/RepositoryName de manera predeterminada. Si tiene acceso de escritura al repositorio de destino, como su bifurcación, GitHub crea en él una rama nueva. El nombre de la rama tiene el formato predeterminado patch-n, en el que se usa un identificador numérico para la rama de la revisión.

Usamos solicitudes de incorporación de cambios para todos los cambios, incluso en el caso de los colaboradores que tienen acceso de escritura. La mayoría de los repositorios protegen la rama predeterminada para que las actualizaciones se tengan que enviar como PR.

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.

Revisión de solicitudes de incorporación de cambios abiertas

Para leer nuevos temas antes de que se publiquen, consulte la cola de PR 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 Docs y consulte las PR 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 dispone de las opciones Comentarios sobre el producto o Comentarios sobre el contenido con las que puede realizar el seguimiento de incidencias que son específicas 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 de esta guía 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.