Cómo contribuir a la documentación de Minecraft Bedrock

2022-04-26

Te damos la bienvenida al repositorio público de la documentación de Minecraft Bedrock. Cualquier artículo que crees o edites en este repositorio será visible para el público.

Los documentos de Minecraft Bedrock están en la plataforma docs.microsoft.com, que usa un Markdown de estilo GitHub con características de Markdig. El contenido que edites en este repositorio se formateará en páginas estilizadas de Microsoft Docs que se ven en documentos de Minecraft Bedrock. El contenido creado por ti y otros miembros de la comunidad Bedrock se publicará como parte de nuestros lanzamientos de contenido y actualizaciones de Minecraft: Bedrock Edition.

En esta página, se detallan los pasos básicos y las pautas para contribuir, así como los enlaces a los fundamentos de Markdown. ¡Gracias por tu contribución!

Repositorios disponibles

Nombre del repositorio	URL
Documentos de Minecraft Bedrock	https://github.com/MicrosoftDocs/minecraft-creator

Antes de que empieces

Si aún no tienes una, tendrás que crear una cuenta de GitHub.

Te recomendamos también estas precauciones de seguridad para cuando configures tu cuenta de GitHub:

Crea una contraseña segura para tu cuenta de Github.
Habilita la autenticación de dos factores.
Guarda tus códigos de recuperación en un lugar seguro.
Actualiza la configuración de tu perfil público.
- Establece tu nombre y considera configurar tu correo electrónico público en la opción Don't show my email address (No mostrar mi dirección de correo electrónico).
- Te recomendamos que cargues una foto de perfil porque se muestra una miniatura en las páginas de los documentos en los que hayas colaborado.
Si planeas usar la línea de comandos, considera configurar Git Credential Manager para Windows. Así, no tendrás que ingresar tu contraseña cada vez que hagas un aporte.

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

Cómo editar un artículo existente

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

Navega hasta el artículo que deseas editar en Documentos de Minecraft Creator .
Selecciona el botón de edición (ícono de lápiz) en la parte superior derecha. Automáticamente, se bifurcará una rama desechable a partir de la rama "main" (principal).

Botón de edición del portal de aprendizaje

Edita el contenido y el formato del artículo utilizando los fundamentos de Markdown.
Actualiza los metadatos en la parte superior de cada artículo:
- title: Título de la página que aparece en la pestaña del navegador cuando se está viendo el artículo. Los títulos de las páginas se utilizan para SEO e indexación, así que no cambies el título a menos que sea necesario (aunque esto es menos crítico antes de que la documentación se haga pública).
- description: Escribe una breve descripción del contenido del artículo; eso potencia el SEO y el descubrimiento.
- author: Si eres el propietario principal de la página, agrega aquí tu alias de GitHub.
- ms.author: Si eres el propietario principal de la página, agrega aquí tu alias de Microsoft (no necesitas @microsoft.com, solo el alias).
- ms.date: Actualiza la fecha si estás agregando contenido importante a la página, pero no para correcciones como aclaraciones, formato, gramática u ortografía.
- keywords: Las palabras clave contribuyen a la SEO (optimización para motores de búsqueda). Agrega palabras clave separadas por una coma y un espacio que sean específicas para tu artículo, pero sin puntuación después de la última palabra clave de tu lista. No es necesario agregar palabras clave globales que se apliquen a todos los artículos, ya que se administran en otros lugares.
Cuando hayas terminado de modificar el artículo, desplázate hacia abajo y selecciona Propose file change (Proponer cambio de archivo).
En la página siguiente, selecciona Create pull request (Crear solicitud de extracción) para que tu rama, que se creó automáticamente, se fusione con "main" (principal).
Repite los pasos anteriores para el siguiente artículo que desees editar.

Cómo eliminar un artículo existente o cambiarle el nombre

Si con tu cambio, se eliminará un artículo existente o se le modificará el nombre, asegúrate de agregar una redirección. De esa manera, toda persona que tenga un vínculo al artículo existente terminará igualmente en el lugar correcto. Los redireccionamientos se administran mediante el archivo .openpublishing.redirection.json en la raíz del repositorio.

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

{
    "redirections": [
        {
            "source_path": "minecraft-creator/creator/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },

source_path es la ruta del repositorio relativa al artículo anterior que estás eliminando. Asegúrate de que la ruta comience con minecraft-creator/creator y termine con .md.
redirect_url es la URL pública relativa del artículo antiguo al artículo nuevo. Asegúrate de que esta URL no contenga minecraft-creator/creator ni .md, ya que se refiere a la URL pública y no a la ruta del repositorio. Puedes vincular a una sección dentro del nuevo artículo usando #section. También puedes utilizar una ruta absoluta a otro sitio aquí si es necesario.
redirect_document_id indica si deseas conservar el ID de documento del archivo anterior. El valor predeterminado es false. Utiliza true si deseas conservar el valor del atributo ms.documentid del artículo redirigido. Si conservas el ID de documento, los datos tales como las visitas a la página y las clasificaciones se transferirán al artículo de destino. Haz esto si la redirección es principalmente un cambio de nombre y no un puntero a un artículo diferente que solo incluye parte del mismo contenido.

Si agregas una redirección, asegúrate de eliminar también el archivo anterior.

Cómo crear un nuevo artículo

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

Crea una bifurcación de la rama "main" (principal) de MicrosoftDocs/minecraft-creator (usando el botón Fork [Bifurcación] en la parte superior derecha).

Botón de bifurcación de GitHub

En la carpeta "creator/Documents", selecciona Add file (Agregar archivo) > Create new file (Crear nuevo archivo) en la parte superior derecha.
Crea un nombre de página para el artículo (usa guiones en lugar de espacios y no uses puntuación ni apóstrofos). Agrega ".md" al final.

Importante

Asegúrate de crear el nuevo artículo desde la carpeta "creator/Documents". Para confirmar esto, comprueba si dice "/creator/Documents" en la línea de nombre del nuevo archivo.

En la parte superior de la nueva página, agrega el siguiente bloque de metadatos:

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

Completa los campos de metadatos relevantes según las instrucciones de la sección anterior.
Escribe el contenido del artículo utilizando los fundamentos de Markdown.
Agrega una sección ## See also en la parte inferior del artículo con vínculos a otros artículos relevantes.
Cuando hayas terminado de escribir el artículo, selecciona Commit new file (Confirmar nuevo archivo).
Selecciona New pull request (Nueva solicitud de extracción) y combina la rama "main" (principal) de tu bifurcación con la rama "main" de MicrosoftDocs/minecraft-creator (asegúrate de que la flecha apunte en la dirección correcta).

Solicitud de extracción de GitHub

Nuestro equipo de contenido revisará tu solicitud de extracción. Si se aprueba, tus cambios se implementarán en nuestro próximo lanzamiento regular. Si tu solicitud de extracción no se aprueba, un miembro del equipo de contenido dejará un comentario en tu solicitud para informarte por qué no se aprobó.

Fundamentos de Markdown

Los siguientes recursos te ayudarán a aprender cómo editar la documentación usando el lenguaje Markdown:

Cómo agregar tablas

Debido a la forma en que docs.microsoft.com les aplica estilos a las tablas, estas no tendrán bordes ni estilos personalizados incluso aunque uses CSS en línea. Parecerá que funciona durante un corto período de tiempo, pero en algún momento la plataforma le quitará el estilo a la tabla. Así que planifica con anticipación y haz que tus tablas sean siempre simples. Aquí tienes un sitio que permite crear tablas con Markdown de manera sencilla.

La extensión Docs Markdown para Visual Studio Code también hace que resulte más fácil crear tablas si usas este editor de código (ver más abajo) para modificar la documentación.

|Title 1 |Title 2| Title 3|
|--------|-------|--------|
|This will |Show a three |column table|

Cómo agregar imágenes

Deberás cargar las imágenes en la carpeta "minecraft-creator/creator/images" del repositorio y, luego, hacer referencia a ellas adecuadamente en el artículo. Las imágenes se mostrarán automáticamente en tamaño completo, lo que significa que las imágenes grandes ocuparán todo el ancho del artículo. Recomendamos ajustar el tamaño de las imágenes antes de subirlas. El ancho recomendado es de entre 600 y 700 píxeles, aunque deberías aumentar 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 puedes cargar imágenes en tu repositorio bifurcado antes de fusionar. Entonces, si planeas agregar imágenes a un artículo, primero deberás usar Visual Studio Code para agregar las imágenes a la carpeta "images" de tu bifurcación o asegurarte de haber hecho lo siguiente en un navegador web:

Bifurcaste el repositorio de MicrosoftDocs/minecraft-creator.
Editaste el artículo en tu bifurcación.
Cargaste las imágenes a las que hace referencia tu artículo en la carpeta "minecraft-creator/creator/images" de tu bifurcación.
Creaste una solicitud de extracción para fusionar tu bifurcación en la rama "main" (principal) de MicrosoftDocs/minecraft-creator.

Para saber cómo configurar tu propio repositorio bifurcado, sigue las instrucciones para crear un nuevo artículo.

Vista previa de tu trabajo

Mientras editas en GitHub a través de un navegador web, puedes seleccionar la pestaña Preview (Vista previa) cerca de la parte superior de la página para obtener una vista previa de tu trabajo antes de confirmar.

Nota

La vista previa de tus cambios en review.docs.microsoft.com solo está disponible para empleados de Microsoft.

Empleados de Microsoft: una vez que sus aportes se hayan fusionado en la rama "main" (principal), puedes revisar el contenido antes de que se haga público en https://github.com/MicrosoftDocs/minecraft-creator/tree/main/creator. Encuentra tu artículo usando la tabla de contenido en la columna de la izquierda.

Edición en un navegador web frente a edición con un cliente de escritorio

Editar en el navegador es la forma más fácil de realizar cambios rápidos, sin embargo, existen algunas desventajas:

No tienes el corrector ortográfico.
No obtienes ningún vínculo inteligente a otros artículos (debes escribir manualmente el nombre de archivo del artículo).
Puede ser complicado cargar imágenes y establecer referencias con ellas.

Si prefieres no lidiar con estos problemas, usa un cliente de escritorio como Visual Studio Code con un par de extensiones útiles para hacer tus aportes.

Uso de Visual Studio Code

Por las razones enumeradas anteriormente, quizás prefieras utilizar un cliente de escritorio para editar la documentación en lugar de un navegador web. Recomendamos utilizar Visual Studio Code.

Configuración

Sigue estos pasos para configurar Visual Studio Code a fin de que funcione con este repositorio:

En un navegador web:

a. Instala Git para tu PC.

b. Instala Visual Studio Code.

c. Bifurca MicrosoftDocs/minecraft-creator si todavía no lo hiciste.

d. En tu bifurcación, selecciona Clone (Clonar) o download (descargar), y copia la URL.
Cree un clon local de tu bifurcación en Visual Studio Code:

a. En el menú View (Ver), selecciona Command Palette (Paleta de comandos).

b. Escribe "Git: Clone".

c. Pega la URL que copiaste.

d. Elige dónde guardar el clon en tu PC.

e. Selecciona Open repo (Abrir repositorio) en la ventana emergente.

Cómo editar la documentación

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