Directrices de creación

En las secciones siguientes se describen las directrices y notas para crear documentación inicial.

Directrices

En las secciones siguientes se describen las directrices técnicas, de diseño y basadas en resultados para la creación de contribuciones.

Metas

A medida que construimos nuestra documentación, es importante considerar cómo permitimos a nuestros lectores Caer en el pozo del éxito.

Brad Abrams definido El pozo del éxito en 2003 como

El pozo del éxito: en marcado contraste con una cumbre, un pico o un viaje a través de un desierto para encontrar la victoria a través de muchas pruebas y sorpresas, queremos que nuestros clientes simplemente caigan en prácticas ganadoras mediante el uso de nuestra plataforma y marcos. En la medida en que hacemos que sea fácil meterse en problemas, fracasamos.

Dado este objetivo, considere lo siguiente:

Proporcionar una “experiencia sin acantilados”
- Ayudar a los administradores y a los equipos de gobierno central a crear un modelo de autoservicio de uso de Kit de automatización para Power Platform
- Permitir a los usuarios hacer uso de entornos de desarrollo para ponerse manos a la obra si un entorno central no está disponible y desean características antes de una implementación de prueba o producción de Kit de automatización para Power Platform
- Discuta el uso de entornos de prueba con una configuración fácil para ponerse manos a la obra con Kit de automatización para Power Platform
Proporcione un canal para la retroalimentación. Dar opciones para que los clientes proporcionen información sobre lo que podemos mejorar

Control de código fuente

Has completado Documentación pasos para descargar y enviar cambios al repositorio de GitHub
Los nuevos cambios se envían a una nueva rama y tienen una solicitud de extracción para revisar los cambios
Toda la documentación debe ser markdown, JSon o activos estáticos que puedan ser controles de versión y revisarse mediante el proceso estándar de solicitud de extracción.

Directrices de diseño

Página principal

Tener un título y subtítulo claros que describan el objetivo de la experiencia inicial
Proporcione un llamado a la acción para incluir otros eventos relacionados. Por ejemplo, regístrese para el horario de oficina.
Enlace a la acción de introducción como acción principal para ayudar a los nuevos usuarios a incorporarse
Acción secundaria para unirse al horario de oficina para ayudar a construir una comunidad de usuarios
Incluir mosaicos de acciones comunes
Lista resumida de características que ayudan a los usuarios a administrar proyectos de hiperautomatización
Navegación de pie de página para vínculos comunes.

Lea el Configuración del sitio para obtener más información sobre la configuración de la página principal.

Reutilización

Utilice diseños de hugo para poder especificar un nuevo tema o anular el tema actual colocando contenido en la carpeta site\layouts
Cambiar los diseños debería permitir que se incluya HTML estático en muchas ubicaciones de alojamiento. Por ejemplo
- Páginas de GitHub
- Páginas de energía
- Compartir punto
- Sitios web estáticos de Azure
El enfoque puede ser utilizado como plantillas por los socios o clientes para crear “paquetes de documentación” para acelerar la fase de nutrición de Kit de automatización para Power Platform documentación
Proporcionar la capacidad para múltiples usuarios de la documentación (por ejemplo, equipos del Centro de excelencia de clientes y socios)
Permitir que se incluya contenido proporcionado por el usuario
Permitir el proceso de actualización que permite extraer nuevos cambios de Kit de automatización para Power Platform Documentación inicial

Páginas de Markdown

Puedes usar Código de Visual Studio Para editar los archivos de Markdown
Los archivos Markdown deben estar ubicados en la carpeta /site/content
Cada archivo de markdown debe incluir un encabezado común en cada página

title: Sample page
description: Automation Kit sample page
sidebar: false
sidebarlogo: fresh-white
include_footer: true

Los archivos Markdown deben usar códigos cortos para incrustar cualquier JavaScript

códigos cortos

Los códigos cortos proporcionan la capacidad de incluir contenido dinámico en una página de rebajas. Puede leer más sobre los códigos cortos en el Documentación de código abreviado de Hugo

Este proyecto también incluye shortcodes adicionales

Tabla de contenidos

Agregue el Toc Siguiendo el shortcode a su Markdown para incluir una tabla de contenido de encabezados Markdown en la página rodeada de {{ y }}

<toc/>

Pregunta

Incluye un conjunto de preguntas en tu página rodeado de {{ y }}

<questions name="/content/en-us/foo.json" completed="Thank you for completing foo" showNavigationButtons=false />

Parámetros:

nombre Nombre del archivo JSon que incluye las preguntas que se van a importar. Leer Preguntas Para obtener más información sobre el formato de archivo de pregunta
completado El texto que se mostrará cuando se completen las preguntas
showNavigationButtons valor verdadero/falso para zapatar Botones de navegación Siguiente/Atrás/Completado

Imagen externa

Incluye una imagen de tamaño de una fuente externa en tu página rodeada de {{ y }}

<externalImage src="https://github.githubassets.com/images/icons/emoji/unicode/1f6a7.png" size="16x16" text="Construction Icon"/>

Parámetros:

Fuente La ruta de origen a la imagen que se va a importar
tamaño El tamaño en píxeles para cambiar el tamaño de la imagen de origen a
Mensaje de texto El texto alternativo que se va a incluir con la imagen

Notas

Configuración de páginas de GitHub

Los siguientes pasos se usaron para configurar las páginas de GitHub para el sitio

Rama Comprobar documentación
```
git checkout gh-pages
```
Hugo extended está instalado
- También puede instalar con chocolatey en Windows
```
choco install hugo-extended -confirm
```
Cambiar a la carpeta del sitio
```
cd site
```
Probar los cambios
```
hugo serve
```
Para crear el sitio html estático dentro de la carpeta del sitio, ejecute el siguiente comando
```
hugo
```
Empuja tu rama gh-pages a GitHub
Configurar el proyecto de GitHub para habilitar Pages
- Consulta Configurar un origen de publicación para tu sitio de Páginas de GitHub - Documentos de GitHub
- Rama gh-pages seleccionada y carpeta /docs

Actualizar la insignia de imagen de la página de inicio

Para personalizar la imagen de la página de inicio a una insignia de vista previa de Estado: Público, hago lo siguiente:

Clonar el repositorio svg-badges

git clone https://github.com/anouarhassine/svg-badges.git
cd svg-badges

Instalar módulos
```
npm install
```
Inicie el servidor web para generar insignias
```
npm run start
```

Generar insignia

http://localhost:9000/static/Status-Public%20Preview-Green

Descargar la insignia svg
Usar inkscape para editar svg existente y guardar resultados
Cargar nueva imagen en la carpeta static\images\illustrations

Cambiar la imagen de config.yaml hero

params:
    hero:
        image: illustrations/worker-public-preview.svg

Preguntas y respuestas

Pregunta ¿Por qué fue seleccionado Hugo?

Hugo es un popular generador de sitios estáticos que permite el contenido de Kit de automatización para Power Platform documentación de inicio para ser transformada a HTML estático que se puede alojar en Páginas de GitHub

Pregunta ¿Por qué no seleccionó algún otro generador de sitios estáticos?

El equipo central de Power CAT tenía experiencia previa usando Hugo

Pregunta ¿Por qué no se usó Microsoft Forms para preguntas?

Uno de los objetivos del diseño fue integrar el proceso de preguntas directamente en el contenido.

Pregunta ¿Por qué las páginas de GitHub para alojar contenido?

El código fuente del Kit de automatización para Power Platform ya existe en GitHub y el soporte nativo de páginas de GitHub fue una opción de dónde alojar el contenido.

Pregunta ¿Por qué este contenido no está activado? http://learn.microsoft.com?

A medida que el contenido madura a una guía comúnmente reutilizable, puede migrar a https://learn.microsoft.com
Un objetivo de diseño clave está habilitado por el alojamiento de GitHub
- Permitir la contribución activa de la comunidad
- Fomentar el proceso de Nutrición del Centro de Excelencia para que la documentación pueda ser reutilizada por la comunidad de clientes y socios

Pregunta ¿Por qué no se aplica el enfoque a otros proyectos de Power CAT?

El Kit de automatización para Power Platform está experimentando con este canal de documentación para complementar y vincular a nuestro Contenido de aprendizaje. Basándonos en los comentarios y el resultado de este experimento, evaluaremos si otros proyectos administrados por Power CAT adoptarán un enfoque similar.

Pregunta ¿Cómo puedo ver los problemas de documentación abierta?

Puedes visitar nuestro Problemas de documentación abierta página

Pregunta ¿Cómo genero una nueva solicitud de característica de documentación?

Crear un nuevo Solicitud de características