Contribución a la documentación para desarrolladores de Mixed Reality

Bienvenido al repositorio público para Mixed Reality documentación para desarrolladores. Todos los artículos que cree o edite en este repositorio serán visibles para el público.

Los documentos de Mixed Reality ahora se hospedan en Microsoft Learn, que usa Markdown con sabor a GitHub con características de Markdig. El contenido que edita en este repositorio se da formato a páginas estilizadas que se muestran en /windows/mixed-reality.

En esta página se tratan los pasos básicos y las directrices para colaborar y los vínculos a los conceptos básicos de Markdown. Gracias por su contribución.

Repositorios disponibles

Nombre del repositorio	URL
Azure Object Anchors	MicrosoftDocs/azure-docs/articles/object-anchors
Azure Remote Rendering	MicrosoftDocs/azure-docs/articles/remote-rendering
Azure Spatial Anchors	MicrosoftDocs/azure-docs/articles/spatial-anchors
HoloLens	MicrosoftDocs/HoloLens
Mixed Reality	MicrosoftDocs/mixed-reality
Guía para los entusiastas de la VR	MicrosoftDocs/mixed-reality/enthusiast-guide

Antes de comenzar

Necesitará crear una cuenta de GitHub si aún no tiene una.

Nota

Si es empleado de Microsoft, vincule su cuenta de GitHub a su alias de Microsoft en el portal de código abierto de Microsoft. Únase a las organizaciones "Microsoft" y "MicrosoftDocs".

Al configurar la cuenta GitHub, también se recomiendan estas precauciones de seguridad:

• Cree una contraseña segura para la cuenta de Github.
• Habilite la autenticación en dos fases.
• Guarde los códigos de recuperación en un lugar seguro.
• Actualice la configuración del perfil público.
  • Establezca su nombre y considere la posibilidad de establecer el correo electrónico público en no mostrar la dirección de correo electrónico.
  • Se recomienda cargar una imagen de perfil porque se muestra una miniatura en las páginas de documentos en las que colabora.
• Si tiene previsto usar la línea de comandos, considere la posibilidad de configurar Git Administrador de credenciales para Windows. De este modo, no tendrá que escribir la contraseña cada vez que realice una colaboración.

El sistema de publicación está asociado a GitHub, por lo que estos pasos son importantes. Aparecerá como autor o colaborador de cada artículo con el alias de GitHub.

Edición de un artículo existente

Use el siguiente flujo de trabajo para realizar actualizaciones en un artículo existente a través de GitHub en un explorador web:

1. Vaya al artículo que desea editar en la carpeta "mixed-reality-docs".

2. Seleccione el botón de edición (icono de lápiz) en la parte superior derecha, que bifurcará automáticamente una rama descartable fuera de la rama "master".

   

3. Edite el contenido del artículo según los "conceptos básicos de Markdown".

4. Actualice los metadatos en la parte superior de cada artículo:

   • title: título de la página que aparece en la pestaña del explorador cuando se visualiza el artículo. Los títulos de página se usan para la SEO e indexación, por lo que no cambie el título a menos que sea necesario (aunque es menos crítico antes de que la documentación se haga pública).
   • description: escriba una breve descripción del contenido del artículo, lo que impulsa la SEO y la detección.
   • author: si es el propietario principal de la página, agregue el alias de GitHub aquí.
   • ms.author: si es el propietario principal de la página, agregue el alias de Microsoft aquí (no necesita @microsoft.com, solo el alias).
   • ms.date: actualice la fecha si agrega contenido principal a la página, pero no para correcciones como aclaraciones, formato, gramática u ortografía.
   • keywords: las palabras clave ayudan en la SEO (optimización del motor de búsqueda). Agregue palabras clave, separadas por una coma y un espacio, que sean específicas del artículo, pero sin signos de puntuación después de la última palabra clave de la lista. No es necesario agregar palabras clave globales que se apliquen a todos los artículos, ya que se administran en otro lugar.

5. Cuando haya completado las modificaciones del artículo, desplácese hacia abajo y seleccione Propose file change (Proponer cambio de archivo).

6. En la página siguiente, seleccione Crear solicitud de incorporación de cambios para combinar la rama creada automáticamente en "master".

7. Repita los pasos anteriores para el siguiente artículo que quiera editar.

Cambio de nombre o eliminación de un artículo existente.

Si el cambio cambiará el nombre o eliminará un artículo existente, asegúrese de agregar una redirección. De este modo, cualquier persona con un vínculo al artículo existente acabará en el lugar correcto. Las redirecciones se administran mediante el archivo .openpublishing.redirection.json en la raíz del repositorio.

Para agregar una redirección a .openpublishing.redirection.json, agregue una entrada a la matriz redirections:

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}

• source_path es la ruta de acceso relativa del repositorio al artículo anterior que está quitando. Asegúrese de que la ruta de acceso comienza por mixed-reality-docs y termina con .md.
• redirect_url es la dirección URL pública relativa del artículo anterior al nuevo. Asegúrese de que esta dirección URL no contiene mixed-reality-docs ni .md, ya que hace referencia a la dirección URL pública y no a la ruta de acceso del repositorio. Se permite la vinculación a una sección dentro del nuevo artículo mediante #section. También puede usar una ruta de acceso absoluta a otro sitio, si es necesario.
• redirect_document_id indica si quiere conservar el id. de documento del archivo anterior. El valor predeterminado es false. Use true si quiere conservar el valor del atributo ms.documentid del artículo redirigido. Si conserva el id. de documento, los datos, como las vistas de página y las clasificaciones, se transferirán al artículo de destino. Use esta solución si el redireccionamiento es principalmente un cambio de nombre y no un puntero a un artículo diferente que solo cubre parte del mismo contenido.

Al agregar un redireccionamiento, asegúrese de eliminar también el archivo anterior.

Creación un nuevo artículo

Use el siguiente flujo de trabajo para crear nuevos artículos en el repositorio de documentación a través de GitHub en un explorador web:

1. Cree una bifurcación fuera de la rama "master" de MicrosoftDocs/mixed-reality (con el botón Bifurcar en la parte superior derecha).

   

2. En la carpeta "mixed-reality-docs", seleccione Crear nuevo archivo en la parte superior derecha.

3. Cree un nombre de página para el artículo (use guiones en lugar de espacios y no use signos de puntuación ni apóstrofos) y agréguele ".md".

   

   Importante

   Asegúrese de crear el nuevo artículo desde la carpeta "mixed-reality-docs". Para confirmarlo, compruebe "/mixed-reality-docs/" en la nueva línea de nombre de archivo.

4. En la parte superior de la nueva página, agregue el siguiente bloque de metadatos:

   ---
   title:
   description:
   author:
   ms.author:
   ms.date:
   ms.topic: article
   keywords:
   ---
   

5. Rellene los campos de metadatos pertinentes según las instrucciones de la sección anterior.

6. Escriba contenido de artículo con los conceptos básicos de Markdown.

7. Agregue una sección ## See also en la parte inferior del artículo con vínculos a otros artículos pertinentes.

8. Cuando termine, seleccione Commit new file (Confirmar nuevo archivo).

9. Seleccione Nueva solicitud de incorporación de cambios y combine la rama "master" de la bifurcación en MicrosoftDocs/mixed-reality "master" (asegúrese de que la flecha apunta de la manera correcta).

   

Aspectos básicos de Markdown

Los siguientes recursos le ayudarán a aprender a editar la documentación mediante el lenguaje Markdown:

• Markdown basics (Conceptos básicos de Markdown)
• Póster de referencia de Markdown de un vistazo
• Recursos adicionales para escribir Markdown para Microsoft Learn

Adición de tablas

Debido a la forma en que las tablas de estilos de documentación técnica de Microsoft, no tendrán bordes ni estilos personalizados, aunque pruebe CSS insertado. Parecerá que funciona durante un breve período de tiempo, pero finalmente la plataforma quitará el estilo de la tabla. Por lo tanto, planee con antelación y mantenga las tablas simples. Este es un sitio que facilita las tablas de Markdown.

La extensión Docs Markdown para Visual Studio Code también facilita la generación de tablas si usa Visual Studio Code (consulte a continuación) para editar la documentación.

Incorporación de imágenes

Deberá cargar las imágenes en la carpeta "mixed-reality-docs/images" del repositorio y, a continuación, hacer referencia a ellas correctamente en el artículo. Las imágenes se mostrarán automáticamente a tamaño completo, lo que significa que las imágenes grandes rellenarán todo el ancho del artículo. Se recomienda dimensionar previamente las imágenes antes de cargarlas. El ancho recomendado es de entre 600 y 700 píxeles, aunque debe aumentar o reducir el tamaño si es una captura de pantalla densa o una fracción de una captura de pantalla, respectivamente.

Importante

Solo puede cargar imágenes en el repositorio bifurcado antes de combinarlas. Por lo tanto, si planea agregar imágenes a un artículo, deberá usar Visual Studio Code para agregar primero las imágenes a la carpeta "images" de la bifurcación o asegúrese de que ha hecho lo siguiente en un explorador web:

1. Bifurcado el repositorio microsoftDocs/mixed-reality.
2. Se ha editado el artículo en la bifurcación.
3. Cargó las imágenes a las que hace referencia en el artículo a la carpeta "mixed-reality-docs/images" de la bifurcación.
4. Ha creado una solicitud de incorporación de cambios para combinar la bifurcación en la rama "master" de MicrosoftDocs/mixed-reality.

Para información sobre cómo configurar su propio repositorio bifurcado, siga las instrucciones para crear un nuevo artículo.

Vista previa del trabajo

Al editar en GitHub a través de un explorador web, puede seleccionar la pestaña Vista previa cerca de la parte superior de la página para obtener una vista previa del trabajo antes de confirmarlo.

Nota

La vista previa de los cambios preconfigurados solo está disponible para los empleados de Microsoft

Empleados de Microsoft: una vez que las contribuciones se han combinado en la rama "main", puede revisar el contenido antes de que pase a público en /windows/mixed-reality?branch=main. Busque el artículo con la tabla de contenido de la columna izquierda.

Edición en el explorador frente a edición con un cliente de escritorio

La edición en el explorador es la manera más fácil de realizar cambios rápidos; sin embargo, hay algunas desventajas:

• No se hace una corrección ortográfica.
• No obtiene ninguna vinculación inteligente a otros artículos (tiene que escribir manualmente el nombre de archivo del artículo).
• Puede ser complicado cargar y hacer referencia a imágenes.

Si prefiere no enfrentarse a estos problemas, use un cliente de escritorio, como Visual Studio Code con un par de extensiones útiles al colaborar.

Uso de Visual Studio Code

Por los motivos mencionados anteriormente, puede que prefiera usar un cliente de escritorio para editar la documentación en lugar de un explorador web. Se recomienda usar Visual Studio Code.

Configurar

Siga estos pasos para configurar Visual Studio Code para trabajar con este repositorio:

1. En un explorador web:
   1. Instale Git para el equipo.
   2. Instale Visual Studio Code.
   3. Bifurque MicrosoftDocs/mixed-reality si aún no lo ha hecho.
   4. En la bifurcación, seleccione Clone or download (Clonar o descargar) y, después, copie la dirección URL.
2. Cree un clon local de la bifurcación en Visual Studio Code:
   1. En el menú Ver, seleccione Paleta de comandos.
   2. Escriba "Git: Clone".
   3. Pegue la dirección URL que copió.
   4. Elija dónde guardar el clon en el equipo.
   5. Seleccione Open repo (Abrir repositorio) en la ventana emergente.

Edición de documentación

Use el siguiente flujo de trabajo para realizar cambios en la documentación con Visual Studio Code:

Nota

Todas las instrucciones para editar y crear artículos, y los conceptos básicos de la edición de Markdown de arriba, también se aplican a Visual Studio Code.

1. Asegúrese de que la bifurcación clonada se ha actualizado con el repositorio oficial.

   1. En un explorador web, cree una solicitud de incorporación de cambios para sincronizar los cambios recientes de otros colaboradores en MicrosoftDocs/mixed-reality "master" en la bifurcación (asegúrese de que la flecha apunta de la manera correcta).

      

   2. En Visual Studio Code, seleccione el botón de sincronización para sincronizar la bifurcación recién actualizada con el clon local.

      

2. Cree o edite artículos en el repositorio clonado mediante Visual Studio Code.

   1. Edite uno o varios artículos (agregue imágenes a la carpeta "images", si es necesario).

   2. Guarde los cambios en Explorador.

      

   3. Confirme todos los cambios en Control de código fuente (escriba el mensaje de confirmación cuando se le solicite).

      

   4. Seleccione el botón de sincronización para volver a sincronizar los cambios en el origen (la bifurcación en GitHub).

      

3. En un explorador web, cree una solicitud de incorporación de cambios para sincronizar nuevos cambios en la bifurcación a MicrosoftDocs/mixed-reality "master" (asegúrese de que la flecha apunta de la manera correcta).

   

Extensiones útiles

Las siguientes extensiones de Visual Studio Code son útiles al editar la documentación:

• Extensión de Docs Markdown para Visual Studio Code: use Alt+M para abrir un menú de opciones de creación de documentos como:
  • Busque y haga referencia a las imágenes que ha cargado.
  • Agregue formatos, como listas, tablas y llamadas específicas de documentos, como >[!NOTE].
  • Busque y haga referencia a vínculos internos y marcadores (vínculos a secciones específicas dentro de una página).
  • Los errores de formato están resaltados (mantenga el mouse sobre el error para más información).
• Corrector ortográfico de código: las palabras mal escritas estarán subrayadas. Haga clic con el botón derecho en una palabra mal escrita para cambiarla o guardarla en el diccionario.