Contribución a la documentación de Internet Information Services (IIS)
En este documento se describe el proceso para colaborar en los artículos y ejemplos de código que se hospedan en el sitio de documentación de IIS. Las contribuciones pueden ser correcciones tipográficas o tan complejas como artículos nuevos.
Los artículos se almacenan en el repositorio como archivos Markdown. Se pueden realizar pequeños cambios en el contenido de un archivo Markdown en el explorador seleccionando el vínculo Editar en la esquina superior derecha de la ventana del explorador. (Si la ventana del explorador es estrecha, deberá expandir la barra Opciones para mostrar el vínculo Editar). Siga las instrucciones para crear una solicitud de incorporación de cambios (PR). Revisaremos la PR y la aceptaremos o sugeriremos cambios.
Necesita tener conocimientos básicos de Git y GitHub.com.
- Abra un asunto que describa qué quiere hacer, como cambiar un artículo existente o crear uno nuevo. Espere la aprobación del equipo antes de dedicar mucho tiempo.
- Bifurque el repositorio iis-docs y cree una rama para los cambios.
- Envíe una solicitud de incorporación de cambios (PR) al administrador con los cambios.
- Si la PR tiene asignada la etiqueta 'cla-required' rellene el contrato de licencia de colaboración (CLA)
- Responder a los comentarios de la PR.
Para consultar un ejemplo en el que este proceso dio lugar a la publicación de un nuevo artículo, vea el problema 67 y la solicitud de extracción 798 en el repositorio de .NET. El nuevo artículo es Documentar el código con comentarios XML.
Los artículos se escriben en DocFx flavored Markdown, que es un superconjunto de GitHub flavored Markdown (GFM). Para obtener ejemplos de sintaxis DFM para las características de interfaz de usuario usadas en la documentación, consulte Metadata and Markdown Template (Metadatos y plantillas de Markdown) en la guía de estilo del repositorio .NET.
Para cada archivo Markdown puede haber una carpeta para imágenes y una carpeta para el código de ejemplo. Por ejemplo, si el artículo es /extensions/advanced-logging-module/advanced-logging-for-iis-client-logging.md, las imágenes se encuentran en extensions/advanced-logging-module/advanced-logging-for-iis-client-loggin/_static y los archivos de proyecto de aplicación de ejemplo se encuentran en extensions/advanced-logging-module/advanced-logging-for-iis-client-loggin/samples. Markdown representa una imagen en el archivo /advanced-logging-for-iis-client-logging.md.
![description of image for alt attribute](advanced-logging-for-iis-client-logging/_static/imagename.png)
Todas las imágenes deben tener texto alternativo.
Los nombres de archivo de Markdown y los nombres de archivo de imagen deben estar en minúsculas.
Los artículos suelen contener fragmentos de código para ilustrar el contenido. DFM permite copiar código en el archivo de Markdown o hacer referencia a un archivo de código independiente. Es preferible usar archivos de código independientes, siempre que sea posible, para minimizar la posibilidad de errores en el código. Los archivos de código deben estar almacenarse en el repositorio con la estructura de carpetas que se ha descrito antes para proyectos de ejemplo.
Estos son algunos ejemplos de sintaxis de fragmento de código DFM que se usaría en un archivo configuration.md.
Para representar un archivo de código completo como un fragmento de código:
[!code-csharp[Main](configuration/sample/Program.cs)]
Para representar una parte de un archivo como un fragmento de código mediante el uso de números de línea:
[!code-csharp[Main](configuration/sample/Program.cs?range=1-10,20,30,40-50]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=1-10,20,30,40-50]
Para fragmentos de código en C#, haga referencia a una región de C#. Siempre que sea posible, use regiones en lugar de números de línea porque los números de línea en un archivo de código tienden a cambiar y dejan de estar sincronizados con las referencias de números de línea en Markdown. Las regiones de C# se pueden anidar y, si se hace referencia a la región externa, las directivas #region
y #endregion
internas no se representan en un fragmento de código.
Para representar una región de C# denominada "snippet_Example":
[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example)]
Para resaltar las líneas seleccionadas en un fragmento representado (normalmente se representa con el color de fondo amarillo):
[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example&highlight=1-3,10,20-25)]
[!code-csharp[Main](configuration/sample/Program.cs?range=10-20&highlight=1-3]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=10-20&highlight=1-3]
[!code-javascript[Main](configuration/sample/Project.json?range=10-20&highlight=1-3]
Pruebe los cambios con la herramienta de línea de comandos DocFX, que crea una versión del sitio hospedada localmente. DocFX no representa las extensiones de sitio y de estilo creadas para learn.microsoft.com.
DocFX requiere .NET Framework en Windows o Mono para Linux o macOS.
Descargue y descomprima docfx.zip desde versiones de DocFX.
Agregue DocFX a la ruta de acceso.
En una ventana de línea de comandos, vaya a la carpeta adecuada que contiene el archivo docfx.json (iis-docs/iis) y ejecute el siguiente comando:
docfx -t default --serve
En un navegador, vaya a
http://localhost:8080
.
Instale Mono a través de Homebrew:
brew install mono
.Descargue la versión más reciente de DocFX.
Extraiga en
\bin\docfx
.Cree un alias para docfx:
function docfx { mono $HOME/bin/docfx/docfx.exe } function docfx-serve { mono $HOME/bin/docfx/docfx.exe serve _site }
Ejecute docfx en el
iis-docs\iis
directorio para compilar el sitio y docfx-serve para ver el sitio enhttp://localhost:8080
.
Nuestro objetivo consiste en escribir documentación que sea fácil de comprender para el público más amplio posible. Con ese fin, hemos establecido directrices para escribir el estilo que queremos que sigan nuestros colaboradores. Para más información, vea Voice and tone guidelines (Directrices de voz y tono) en el repositorio de .NET.
Si elimina un artículo, cambie su nombre de archivo o muévalo a otra carpeta, cree una redirección para que las personas que marcan el artículo no obtengan errores 404. Agregue redireccionamientos al archivo de redireccionamiento principal.