Contribución a la documentación para desarrolladores de realidad mixtaContributing to Mixed Reality developer documentation

Este es el repositorio público de la documentación para desarrolladores de realidad mixta.Welcome to the public repo for Mixed Reality developer documentation! Los artículos que cree o edite en este repositorio serán visibles para el público.Any articles you create or edit in this repo will be visible to the public.

Los documentos de realidad mixta se encuentran ahora en la plataforma docs.microsoft.com, que usa Markdown con funcionalidad de GitHub con características de Markdig.The Mixed Reality docs are now on the docs.microsoft.com platform, which uses GitHub-flavored Markdown with Markdig features. El contenido que se edita en este repositorio se formatea en páginas estilizadas que se muestran en https://docs.microsoft.com/windows/mixed-reality .The content you edit in this repo gets formatted into stylized pages that show up at https://docs.microsoft.com/windows/mixed-reality.

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.This page covers the basic steps and guidelines for contributing and links to Markdown basics. Gracias por su contribución.Thank you for your contribution!

Repositorios disponiblesAvailable repos

Nombre del repositorioRepository name URLURL
Mixed RealityMixed Reality MicrosoftDocs/Mixed-RealityMicrosoftDocs/mixed-reality
Guía de entusiastas de la VRVR Enthusiasts Guide MicrosoftDocs/Mixed-Reality/entusiasta-GuideMicrosoftDocs/mixed-reality/enthusiast-guide
HoloLensHoloLens MicrosoftDocs/HoloLensMicrosoftDocs/HoloLens

Antes de empezarBefore you start

Si aún no tiene una, deberá crear una cuenta de github.If you don't already have one, you'll need to create a GitHub account.

Nota

Si es un empleado de Microsoft, vincule su cuenta de GitHub a su alias de Microsoft en el portal de código abierto de Microsoft.If you're a Microsoft employee, link your GitHub account to your Microsoft alias on the Microsoft Open Source portal. Únase a las organizaciones "Microsoft" y "MicrosoftDocs" .Join the "Microsoft" and "MicrosoftDocs" organizations.

Al configurar la cuenta de GitHub, también se recomiendan estas precauciones de seguridad:When setting up your GitHub account, we also recommend these security precautions:

El sistema de publicación está asociado a GitHub, por lo que estos pasos son importantes.The publishing system is tied to GitHub, so these steps are important. Aparecerá como autor o colaborador en cada artículo mediante el alias de GitHub.You'll be listed as either author or contributor to each article using your GitHub alias.

Edición de un artículo existenteEditing an existing article

Use el siguiente flujo de trabajo para efectuar actualizaciones en un artículo existente a través de github en un explorador Web:Use the following workflow to make updates to an existing article via GitHub in a web browser:

  1. Navegue hasta el artículo que desea editar en la carpeta "Mixed Reality-docs".Navigate to the article you wish to edit in the "mixed-reality-docs" folder.

  2. Seleccione el botón Editar (icono de lápiz) en la parte superior derecha, que bifurcará automáticamente una rama descartable fuera de la rama "principal".Select the edit button (pencil icon) in the top right, which will automatically fork a disposable branch off the 'master' branch.

    Edite un artículo.

  3. Edite el contenido del artículo según los "conceptos básicos de Markdown".Edit the content of the article according to the "Markdown basics".

  4. Actualice los metadatos en la parte superior de cada artículo:Update metadata at the top of each article:

    • título: título de la página que aparece en la pestaña del explorador cuando se está viendo el artículo.title: Page title that appears in the browser tab when the article is being viewed. Los títulos de página se utilizan 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).Page titles are used for SEO and indexing, so don't change the title unless necessary (though this is less critical before documentation goes public).
    • Descripción: escriba una breve descripción del contenido del artículo, que aumenta la SEO y la detección.description: Write a brief description of the article's content, which boosts SEO and discovery.
    • autor: si es el propietario principal de la página, agregue aquí su alias de github.author: If you're the primary owner of the page, add your GitHub alias here.
    • MS. Author: si es el propietario principal de la página, agregue aquí su alias de Microsoft (no es necesario @microsoft.com , solo el alias).ms.author: If you're the primary owner of the page, add your Microsoft alias here (you don't need @microsoft.com, just the 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.ms.date: Update the date if you're adding major content to the page, but not for fixes like clarification, formatting, grammar, or spelling.
    • palabras clave: ayuda de palabras clave en SEO (optimización del motor de búsqueda).keywords: Keywords aid in SEO (search engine optimization). Agregue palabras clave, separadas por una coma y un espacio, específicas de su artículo, pero sin puntuación después de la última palabra clave de la lista.Add keywords, separated by a comma and a space, that are specific to your article, but no punctuation after the last keyword in your list. No es necesario agregar palabras clave globales que se apliquen a todos los artículos, ya que se administran en otro lugar.You don't need to add global keywords that apply to all articles, as those are managed elsewhere.
  5. Cuando haya completado las ediciones del artículo, desplácese hacia abajo y seleccione proponer cambio de archivo.When you've completed your article edits, scroll down and select Propose file change.

  6. En la página siguiente, seleccione crear solicitud de incorporación de cambios para fusionar mediante combinación la rama creada automáticamente en ' maestra '.On the next page, select Create pull request to merge your automatically created branch into 'master.'

  7. Repita los pasos anteriores para el siguiente artículo que desee editar.Repeat the steps above for the next article you want to edit.

Cambiar el nombre o eliminar un artículo existenteRenaming or deleting an existing article

Si el cambio cambiará el nombre o eliminará un artículo existente, asegúrese de agregar una redirección.If your change will rename or delete an existing article, be sure to add a redirect. De este modo, todos los usuarios con un vínculo al artículo existente seguirán en el lugar correcto.That way, anyone with a link to the existing article will still end up in the right place. Las redirecciones las administra el .openpublishing.redirection.jsen el archivo en la raíz del repositorio.Redirects are managed by the .openpublishing.redirection.json file in the root of the repo.

Para agregar una redirección a .openpublishing.redirection.js, agregue una entrada a la redirections matriz:To add a redirect to .openpublishing.redirection.json, add an entry to the redirections array:

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • source_pathEs la ruta de acceso relativa del repositorio al artículo anterior que se va a quitar.The source_path is the relative repository path to the old article that you're removing. Asegúrese de que la ruta de acceso comienza con mixed-reality-docs y termina con .md .Be sure the path starts with mixed-reality-docs and ends with .md.
  • redirect_urlEs la dirección URL pública relativa del artículo anterior al nuevo artículo.The redirect_url is the relative public URL from the old article to the new article. Asegúrese de que esta dirección URL no contiene mixed-reality-docs o .md , ya que hace referencia a la dirección URL pública y no a la ruta de acceso del repositorio.Be sure that this URL doesn't contain mixed-reality-docs or .md, as it refers to the public URL and not the repository path. Se permite la vinculación a una sección del nuevo artículo con #section .Linking to a section within the new article using #section is allowed. También puede usar una ruta de acceso absoluta a otro sitio, si es necesario.You can also use an absolute path to another site here, if necessary.
  • redirect_document_id indica si desea conservar el identificador de documento del archivo anterior.redirect_document_id indicates whether you would like to keep the document ID from the previous file. De manera predeterminada, es false.The default is false. Use true si desea conservar el ms.documentid valor de atributo del artículo redirigido.Use true if you want to preserve the ms.documentid attribute value from the redirected article. Si conserva el identificador de documento, los datos, como las vistas de página y las clasificaciones, se transferirán al artículo de destino.If you preserve the document ID, data, such as page views and rankings, will be transferred to the target article. Haga esto si el redireccionamiento es principalmente un cambio de nombre y no un puntero a un artículo diferente que solo trata parte del mismo contenido.Do this if the redirect is primarily a rename, and not a pointer to different article that only covers some of the same content.

Si agrega un redireccionamiento, asegúrese de eliminar también el archivo antiguo.If you add a redirect, be sure to delete the old file as well.

Creación de un nuevo artículoCreating a new article

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:Use the following workflow to create new articles in the documentation repo via GitHub in a web browser:

  1. Cree una bifurcación desconectada de la rama "principal" de MicrosoftDocs/Mixed Reality (con el botón bifurcar en la parte superior derecha).Create a fork off the MicrosoftDocs/mixed-reality 'master' branch (using the Fork button in the top right).

    Bifurcar la bifurcación principal.

  2. En la carpeta "Mixed Reality-docs", seleccione crear nuevo archivo en la parte superior derecha.In the "mixed-reality-docs" folder, select Create new file in the top right.

  3. Crear un nombre de página para el artículo (usar guiones en lugar de espacios y no usar signos de puntuación ni apóstrofos) y anexar ". MD"Create a page name for the article (use hyphens instead of spaces and don't use punctuation or apostrophes) and append ".md"

    Asigne un nombre a la nueva página.

    Importante

    Asegúrese de crear el nuevo artículo desde la carpeta "Mixed Reality-docs".Make sure you create the new article from within the "mixed-reality-docs" folder. Puede confirmarlo comprobando "/Mixed-Reality-docs/" en la nueva línea de nombre de archivo.You can confirm this by checking for "/mixed-reality-docs/" in the new file name line.

  4. En la parte superior de la página nueva, agregue el siguiente bloque de metadatos:At the top of your new page, add the following metadata block:

    ---
    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.Fill in the relevant metadata fields per the instructions in the section above.

  6. Escriba el contenido del artículo con los conceptos básicos de Markdown.Write article content using Markdown basics.

  7. Agregue una ## See also sección en la parte inferior del artículo con vínculos a otros artículos relevantes.Add a ## See also section at the bottom of the article with links to other relevant articles.

  8. Cuando termine, seleccione confirmar nuevo archivo.When finished, select Commit new file.

  9. Seleccione nueva solicitud de incorporación de cambios y combine la rama ' maestra ' de la bifurcación en MicrosoftDocs/mixed-reality ' maestra ' (Asegúrese de que la flecha señala la manera correcta).Select New pull request and merge your fork's 'master' branch into MicrosoftDocs/mixed-reality 'master' (make sure the arrow is pointing the correct way).

    Cree una solicitud de incorporación de cambios de la bifurcación en MicrosoftDocs/Mixed-Reality

Aspectos básicos de MarkdownMarkdown basics

Los siguientes recursos le ayudarán a aprender a editar la documentación con el lenguaje Markdown:The following resources will help you learn how to edit documentation using the Markdown language:

Agregar tablasAdding tables

Debido a la forma en que docs.microsoft.com las tablas de estilos, no tendrán bordes ni estilos personalizados, aunque pruebe CSS en línea.Because of the way docs.microsoft.com styles tables, they won’t have borders or custom styles, even if you try inline CSS. Parecerá que funciona durante un breve período de tiempo, pero finalmente la plataforma eliminará el estilo de la tabla.It will appear to work for a short period of time, but eventually the platform will strip the styling out of the table. Por tanto, planee con facilidad y mantenga las tablas sencillas.So plan ahead and keep your tables simple. Este es un sitio que facilita las tablas de Markdown.Here’s a site that makes Markdown tables easy.

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.The Docs Markdown Extension for Visual Studio Code also makes table generation easy if you're using Visual Studio Code (see below) to edit the documentation.

Agregar imágenesAdding images

Tendrá que 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.You’ll need to upload your images to the "mixed-reality-docs/images" folder in the repo, and then reference them appropriately in the article. Las imágenes se mostrarán automáticamente a tamaño completo, lo que significa que las imágenes grandes llenarán todo el ancho del artículo.Images will automatically show up at full-size, which means large images will fill the entire width of the article. Se recomienda ajustar el tamaño de las imágenes antes de cargarlas.We recommend pre-sizing your images before uploading them. El ancho recomendado es de entre 600 y 700 píxeles, aunque debe ajustarse verticalmente o reducirse si es una captura de pantalla densa o una fracción de una captura de pantalla, respectivamente.The recommended width is between 600 and 700 pixels, though you should size up or down if it’s a dense screenshot or a fraction of a screenshot, respectively.

Importante

Solo puede cargar imágenes en el repositorio bifurcado antes de la combinación.You can only upload images to your forked repo before merging. Por lo tanto, si planea agregar imágenes a un artículo, deberá usar Visual Studio Code para agregar las imágenes a la carpeta "images" de la bifurcación en primer lugar o asegurarse de que ha realizado lo siguiente en un explorador Web:So, if you plan on adding images to an article, you'll need to use Visual Studio Code to add the images to your fork's "images" folder first or make sure you've done the following in a web browser:

  1. Se ha bifurcado el repositorio MicrosoftDocs/Mixed Reality.Forked the MicrosoftDocs/mixed-reality repo.
  2. Editó el artículo en la bifurcación.Edited the article in your fork.
  3. Cargó las imágenes a las que hace referencia en el artículo en la carpeta "Mixed Reality-docs/Images" de la bifurcación.Uploaded the images you're referencing in your article to the "mixed-reality-docs/images" folder in your fork.
  4. Se creó una solicitud de incorporación de cambios para fusionar mediante combinación la bifurcación en la rama "principal" de MicrosoftDocs/Mixed Reality.Created a pull request to merge your fork into the MicrosoftDocs/mixed-reality 'master' branch.

Para obtener información sobre cómo configurar su propio repositorio bifurcado, siga las instrucciones para crear un nuevo artículo.To learn how to set up your own forked repo, follow the instructions for creating a new article.

Obtener una vista previa del trabajoPreviewing your work

Mientras edita en GitHub a través de un explorador Web, puede seleccionar la pestaña de vista previa situada cerca de la parte superior de la página para obtener una vista previa del trabajo antes de confirmar.While editing in GitHub via a web browser, you can select the Preview tab near the top of the page to preview your work before committing.

Nota

La vista previa de los cambios en review.docs.microsoft.com solo está disponible para los empleados de MicrosoftPreviewing your changes on review.docs.microsoft.com is only available to Microsoft employees

Empleados de Microsoft: una vez que las contribuciones se han combinado en la rama "principal", puede revisar el contenido antes de que se haga público en https://review.docs.microsoft.com/windows/mixed-reality?branch=master .Microsoft employees: once your contributions have been merged into the 'master' branch, you can review the content before it goes public at https://review.docs.microsoft.com/windows/mixed-reality?branch=master. Busque el artículo mediante la tabla de contenido de la columna izquierda.Find your article using the table of contents in the left column.

Edición en el explorador frente a edición con un cliente de escritorioEditing in the browser vs. editing with a desktop client

La edición en el explorador es la forma más sencilla de realizar cambios rápidos; sin embargo, hay algunas desventajas:Editing in the browser is the easiest way to make quick changes, however, there are a few disadvantages:

  • No obtiene la revisión ortográfica.You don't get spell-check.
  • No obtiene ninguna vinculación inteligente a otros artículos (tiene que escribir manualmente el nombre de archivo del artículo).You don't get any smart-linking to other articles (you have to manually type the article's filename).
  • Puede ser una molestia para cargar y hacer referencia a las imágenes.It can be a hassle to upload and reference images.

Si prefiere no tratar estos problemas, use un cliente de escritorio como Visual Studio Code con un par de extensiones útiles al contribuir.If you'd rather not deal with these issues, use a desktop client like Visual Studio Code with a couple helpful extensions when contributing.

Uso de Visual Studio CodeUsing Visual Studio Code

Por los motivos mencionados anteriormente, es posible que prefiera usar un cliente de escritorio para editar la documentación en lugar de un explorador Web.For the reasons listed above, you may prefer using a desktop client to edit documentation instead of a web browser. Se recomienda el uso de Visual Studio Code.We recommend using Visual Studio Code.

ConfigurarSetup

Siga estos pasos para configurar Visual Studio Code para trabajar con este repositorio:Follow these steps to configure Visual Studio Code to work with this repo:

  1. En un explorador Web:In a web browser:
    1. Instale git para su PC.Install Git for your PC.
    2. Instale Visual Studio Code.Install Visual Studio Code.
    3. Bifurcación MicrosoftDocs/Mixed-Reality si todavía no lo ha hecho.Fork MicrosoftDocs/mixed-reality if you haven't already.
    4. En la bifurcación, seleccione clonar o descargar y copiar la dirección URL.In your fork, select Clone or download and copy the URL.
  2. Cree un clon local de la bifurcación en Visual Studio Code:Create a local clone of your fork in Visual Studio Code:
    1. En el menú Ver , seleccione paleta de comandos.From the View menu, select Command Palette.
    2. Escriba "git: Clone".Type "Git: Clone."
    3. Pegue la dirección URL que ha copiado.Paste the URL you copied.
    4. Elija dónde desea guardar el clon en su PC.Choose where to save the clone on your PC.
    5. Seleccione abrir repositorio en el menú emergente.Select Open repo in the pop-up.

Editar documentaciónEditing documentation

Use el siguiente flujo de trabajo para realizar cambios en la documentación con Visual Studio Code:Use the following workflow to make changes to the documentation with Visual Studio Code:

Nota

Todas las instrucciones para Editar y crear artículos, y los aspectos básicos de la edición de Markdown, de lo anterior se aplican también cuando se usa Visual Studio Code.All the guidance for editing and creating articles, and the basics of editing Markdown, from above applies when using Visual Studio Code as well.

  1. Asegúrese de que la bifurcación clonada esté actualizada con el repositorio oficial.Make sure your cloned fork is up to date with the official repo.

    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 ' maestra ' en la bifurcación (Asegúrese de que la flecha señala el modo correcto).In a web browser, create a pull request to sync recent changes from other contributors in MicrosoftDocs/mixed-reality 'master' to your fork (make sure the arrow is pointing the right way).

      Sincronización de los cambios de MicrosoftDocs/Mixed-Reality en la bifurcación

    2. En Visual Studio Code, seleccione el botón sincronizar para sincronizar la bifurcación recién actualizada con el clon local.In Visual Studio Code, select the sync button to sync your freshly updated fork to the local clone.

      Haga clic en la imagen del botón sincronizar

  2. Cree o edite artículos en el repositorio clonado mediante Visual Studio Code.Create or edit articles in your cloned repo using Visual Studio Code.

    1. Edite uno o varios artículos (agregue imágenes a la carpeta "images" si es necesario).Edit one or more articles (add images to “images” folder if necessary).

    2. Guarde los cambios en el Explorador.Save changes in Explorer.

      Elija "guardar todo" en el explorador.

    3. Confirmar todos los cambios en el control de código fuente (escribir mensaje de confirmación cuando se le solicite).Commit all changes in Source Control (write commit message when prompted).

      Elegir "confirmar todo" en el control de código fuente

    4. Seleccione el botón sincronizar para volver a sincronizar los cambios con el origen (la bifurcación en GitHub).Select the sync button to sync your changes back to origin (your fork on 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 de nuevo en MicrosoftDocs/mixed-reality ' maestra ' (Asegúrese de que la flecha señala la manera correcta).In a web browser, create a pull request to sync new changes in your fork back to MicrosoftDocs/mixed-reality 'master' (make sure the arrow is pointing the correct way).

    Cree una solicitud de incorporación de cambios de la bifurcación en MicrosoftDocs/Mixed-Reality

Extensiones útilesUseful extensions

Las siguientes extensiones de Visual Studio Code son útiles al editar la documentación:The following Visual Studio Code extensions are useful when editing documentation:

  • La extensión de Markdown de docs para Visual Studio Code : use Alt + M para abrir un menú de opciones de creación de docs como:Docs Markdown Extension for Visual Studio Code - Use Alt+M to bring up a menu of docs authoring options like:
    • Imágenes de búsqueda y de referencia que ha cargado.Search and reference images you've uploaded.
    • Agregue formato como listas, tablas y llamadas específicas de documentos como >[!NOTE] .Add formatting like lists, tables, and docs-specific call-outs like >[!NOTE].
    • Buscar y hacer referencia a vínculos internos y marcadores (vínculos a secciones específicas de una página).Search and reference internal links and bookmarks (links to specific sections within a page).
    • Los errores de formato se resaltan (mantenga el mouse sobre el error para obtener más información).Formatting errors are highlighted (hover your mouse over the error to learn more).
  • Corrector ortográfico de código : las palabras mal escritas se subrayan; Haga clic con el botón derecho en una palabra mal escrita para cambiarla o guardarla en el diccionario.Code Spell Checker - misspelled words will be underlined; right-click on a misspelled word to change it or save it to the dictionary.