Compartir vía

Acerca de wikis, archivos LÉAME y Markdown

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Puede apoyar a su equipo y los colaboradores del proyecto mediante Markdown para agregar formato enriquecido, tablas e imágenes a su proyecto de equipo. El formato Markdown mejora las páginas wiki del proyecto de equipo, el contenido que agregue a un panel, el archivo LÉAME del proyecto de equipo u otros archivos LÉAME del repositorio.

Configuración de una wiki del proyecto

Una wiki del proyecto de equipo le permite compartir información sobre el proyecto con otros miembros del equipo. Al configurar una wiki desde cero, un nuevo repositorio de Git almacena los archivos de Markdown (.md), las imágenes, los datos adjuntos y la secuencia de páginas. La wiki admite la edición colaborativa de su contenido y estructura.

En los vínculos siguientes se describen las características admitidas para una wiki del proyecto de equipo.

Creación de una nueva wiki

Trabajar con contenido wiki

Dar formato al contenido wiki

Publicación de repositorios de Git en una wiki

Muchos equipos documentan su código mediante archivos Markdown, que se guardan en el repositorio junto con su código. Aunque Git admite el mantenimiento y la revisión de los archivos de documentación de código mediante el proceso de solicitud de incorporación de cambios estándar, estos archivos pueden presentar desafíos a los consumidores del contenido.

  • El usuario a menudo debe examinar muchos archivos y carpetas para encontrar el contenido de interés.
  • El contenido carece de organización y estructura. No hay ninguna jerarquía de página inherente para admitir lectores.
  • No se admite el control de versiones de contenido.
  • La búsqueda a través del contenido se basa en buscar en el código en lugar de en una experiencia de búsqueda optimizada para buscar contenido.

Con la característica Publicar código como wiki , puede publicar uno o varios repositorios de Git definidos en el proyecto de equipo en una wiki. Esta característica proporciona una manera de mantener la documentación de código de forma sincrónica con la base de código y le permite publicar y actualizar de forma selectiva la documentación a una wiki.

Hay diferencias significativas entre la forma de administrar el contenido en una wiki de un proyecto de equipo frente a las páginas wiki que publica desde un repositorio de Git. Para obtener más información, consulte Publicación de un repositorio de Git en una wiki.

Mejora del contenido del proyecto con Markdown

El formato Markdown facilita el formato de texto e incluye imágenes. También puede vincular a documentos dentro de las páginas del proyecto, archivos LÉAME, paneles y solicitudes de incorporación de cambios.

Puede usar Markdown para proporcionar instrucciones al equipo de las siguientes maneras:

Para ver la sintaxis admitida, consulte Uso de Markdown en Azure DevOps.

Agregar archivos LÉAME del proyecto

Puede definir un archivo LÉAME o varios archivos para cada repositorio o proyecto de equipo. Escriba el ARCHIVO LÉAME en Markdown en lugar de texto sin formato. Utilice páginas LÉAME para orientar a los colaboradores sobre información o ubicaciones específicas de su proyecto.

Considere la posibilidad de agregar las instrucciones siguientes:

  • Enfoque del proyecto
  • Requisitos previos
  • Configuración del entorno
  • Sugerencias para hacer cosas dentro del proyecto
  • Propósito o uso de archivos específicos
  • Términos y acrónimos específicos del proyecto
  • Guía de flujo de trabajo sobre cómo confirmar o cargar cambios y agregar ramas
  • Patrocinadores o contactos del proyecto

Ejemplos LÉAME

Estos son algunos ejemplos de READMEs de proyectos en GitHub que son accesibles para todos los usuarios para referencia e inspiración.