Leer en inglés

Compartir a través de


Contribución a la documentación de HoloLens

Bienvenido a la documentación de HoloLens! Los artículos que cree o edite en este repositorio estarán visibles para el público.

La documentación de HoloLens se publica 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 aparecen en /hololens.

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

Repositorios disponibles

Nombre del repositorio URL
HoloLens microsoftDocs/HoloLens
Realidad mixta microsoftDocs/mixed-reality
Guía para entusiastas de VR microsoftDocs/mixed-reality/enthusiast-guide

Antes de empezar

Si aún no tiene una, deberá crear una cuenta de GitHub.

Nota

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

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

  • Cree una contraseña segura para la cuenta de GitHub.
  • Habilite 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 el nombre y considere la posibilidad de establecer el de correo electrónico público en No mostrar mi dirección de correo electrónico.
    • Se recomienda cargar una imagen de perfil porque se muestra una miniatura en los artículos de Microsoft Learn a los que contribuye.
  • Si planea usar la línea de comandos, considere la posibilidad de configurar Administrador de credenciales de Git para Windows. De este modo, no tendrá que escribir su contraseña cada vez que realice una contribución.

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

Edición de un artículo existente

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

  1. Vaya al artículo que desea editar en la carpeta "hololens".

  2. Seleccione el botón editar (icono de lápiz) en la parte superior derecha.

    Editar un artículo.

    Esto bifurcará automáticamente una rama descartable de la rama predeterminada, principal.

  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:

    • título: título de página que aparece en la pestaña del explorador cuando se está viendo el artículo. Los títulos de página se usan para SEO e indexación, por lo que no cambie el título a menos que sea necesario (aunque esto es menos crítico antes de que la documentación sea pública).
    • descripción: escriba una breve descripción del contenido del artículo, lo que aumenta el SEO y la detección.
    • autor: 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 va a agregar contenido principal a la página, pero no para correcciones como aclaración, formato, gramática o ortografía.
    • palabras clave: palabras clave ayudan en SEO (optimización del motor de búsqueda). Agregue palabras clave, separadas por una coma y un espacio, que sean específicas de su artículo, pero sin 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 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 la rama predeterminada, principal.

  7. Repita los pasos anteriores para el siguiente artículo que desea 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 un redireccionamiento. De este modo, cualquier persona con un vínculo al artículo existente seguirá apareciendo en el lugar correcto. Los redireccionamientos se administran mediante el archivo .openpublishing.redirection.json en la raíz del repositorio.

Para agregar un redireccionamiento a .openpublishing.redirection.json, agregue una entrada a la matriz de redirections:

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • El source_path es la ruta de acceso del repositorio relativa al artículo anterior que va a quitar. Asegúrese de que la ruta de acceso comienza con el conjunto de documentos (en este caso, hololens) e incluye la extensión de archivo .md.

  • El redirect_url es la dirección URL pública relativa del artículo anterior al nuevo artículo. Asegúrese de que esta dirección URL no contenga .md e comience con /, ya que hace referencia a la dirección URL pública y no a la ruta de acceso del repositorio. Se permite vincular a una sección del nuevo artículo mediante #section. También puede usar una ruta de acceso absoluta a otro sitio aquí, si es necesario.

  • redirect_document_id indica si desea mantener el identificador del documento del archivo anterior. El valor predeterminado es false. Use true si desea conservar el valor del atributo ms.documentid del artículo redirigido. Si conserva el identificador del documento, los datos, como las vistas de página y las clasificaciones, se transferirán al artículo de destino. Haga esto si el redireccionamiento es principalmente un cambio de nombre y no un puntero a otro artículo que solo cubre parte del mismo contenido.

Si agrega una redirección, asegúrese de eliminar también el archivo antiguo.

Creación de 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 predeterminada, principal, de MicrosoftDocs/hololens mediante el botón Bifurcación de la parte superior derecha.

    Bifurcar la rama predeterminada, actualmente denominada

  2. En la carpeta "hololens", 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 o apóstrofos) y anexe ".md"

    Asigne un nombre a la nueva página.

    Importante

    Asegúrese de crear el nuevo artículo desde la carpeta "hololens". Para confirmarlo, compruebe "/hololens/" 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 como se ha descrito anteriormente en Edición de un artículo existente.

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

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

  8. Cuando termine, seleccione Confirmar nuevo archivo.

  9. Seleccione nueva solicitud de incorporación de cambios y combine la rama principal de de la bifurcación de la bifurcación en MicrosoftDocs/hololens principal (asegúrese de que la flecha apunta al destino correcto).

    Crear solicitud de incorporación de cambios de la bifurcación en MicrosoftDocs/hololens.

Conceptos básicos de Markdown

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

Adición de tablas

Debido a cómo se aplica estilo a las tablas en Microsoft Learn, no tendrán bordes ni estilos personalizados, incluso si prueba CSS insertado. Parecerá que funciona durante un breve período de tiempo, pero finalmente la plataforma quitará el estilo de la tabla. Así que planee con antelación y mantenga las tablas sencillas. Este es un sitio que facilita las tablas de Markdown: [Generador de tablas]](https://www.tablesgenerator.com/markdown_tables).

La extensión markdown de Docs 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.

Adición de imágenes

Deberá cargar las imágenes en la carpeta "hololens/images" del repositorio y, a continuación, hacer referencia a ellas correctamente en el artículo. Las imágenes se mostrarán automáticamente en tamaño completo, lo que significa que las imágenes grandes rellenarán todo el ancho del artículo. Se recomienda cambiar el tamaño previo de las imágenes antes de cargarlas. El ancho recomendado está entre 600 y 700 píxeles, aunque debe ajustar o reducir el tamaño si se trata de 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, primero deberá usar Visual Studio Code para agregar las imágenes a la carpeta "imágenes" de la bifurcación o asegúrese de que ha hecho lo siguiente en un explorador web:

  1. Bifurcado el repositorio MicrosoftDocs/hololens.
  2. Editó el artículo de la bifurcación.
  3. Cargó las imágenes a las que hace referencia en el artículo a la carpeta "hololens/images" de la bifurcación.
  4. Ha creado una solicitud de incorporación de cambios para combinar la bifurcación en la rama principal de MicrosoftDocs/hololens.

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

Vista previa del trabajo

Durante la edición 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 en Microsoft Learn solo está disponible para los empleados de Microsoft.

Empleados de Microsoft: cuando las contribuciones se han combinado en la rama predeterminada, principal, puede revisar el contenido antes de que se publique en </hololens?branch=main>. Busque el artículo mediante 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, pero hay algunas desventajas:

  • No tienes revisió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 una molestia cargar y hacer referencia a imágenes.

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

Uso de Visual Studio Code

Por los motivos enumerados anteriores, 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.

Arreglo

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

  1. En un explorador web:
    1. Instale Git para el equipo.
    2. Instale de Visual Studio Code.
    3. Fork MicrosoftDocs/hololens si aún no lo ha hecho.
    4. En la bifurcación, seleccione Clonar o descargar y 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 Abrir repositorio en el elemento emergente.

Documentación de edición

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

Nota

Todas las instrucciones para edición de y crear artículos de, así como los conceptos básicos de edición de Markdown, se aplican también al usar Visual Studio Code.

  1. Asegúrese de que la bifurcación clonada está actualizada 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 la rama predeterminada de MicrosoftDocs/hololens, principal, en la bifurcación (asegúrese de que la flecha apunta al destino correcto).

      Sincronización cambia de MicrosoftDocs/hololens a la bifurcación.

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

      Haga clic en la imagen del botón sincronizar.

  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. Guardar cambios en Explorer.

      elegir

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

      elegir de control de código fuente

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

      Haga clic en el botón sincronizar.

  3. En un explorador web, cree una solicitud de incorporación de cambios para sincronizar nuevos cambios en la bifurcación a MicrosoftDocs/hololens principal (asegúrese de que la flecha apunta al destino correcto).

    Crear solicitud de incorporación de cambios de la bifurcación en MicrosoftDocs/hololens.

Extensiones útiles

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

  • extensión Markdown de Docs para Visual Studio Code: use Alt+M para abrir un menú de opciones de creación de Microsoft Learn como:

    • Buscar y hacer referencia a imágenes que ha cargado.
    • Agregue formato como listas, tablas y llamadas como >[!NOTE].
    • Buscar y hacer referencia a vínculos internos y marcadores (vínculos a secciones específicas dentro de una página).
    • Los errores de formato se resaltan (mantenga el mouse sobre el error para obtener más información).
  • corrector ortográfico de código : se subrayarán palabras mal escritas; Haga clic con el botón derecho en una palabra mal escrita para cambiarla o guardarla en el diccionario.