Crear un sitio web de documentación

La documentación viene en muchas formas y formatos. Puede que ya tengas algunos recursos o necesites empezar desde cero. Veamos cómo agregar contenido con Archbee.

Una vez que creas un nuevo documento, puedes comenzar a agregar contenido usando ya sea atajos de markdown o cualquiera de los más de 30 bloques personalizados.

Los bloques personalizados te ayudan a dar formato al contenido como lo necesites. Para abrirlos, escribe una barra inclinada / en el editor y revisa las opciones.

Los bloques se agrupan bajo Básico, Medios, Desarrollador, Incrustar, y Reutilización de contenido.

Por ejemplo, si quieres enlazar dinámicamente a otros documentos, escribe @ y el título del documento. Esto se conectará al ID del documento. Si cambias el título o la posición del documento, el enlace siempre apuntará a él.

Otro ejemplo es llamar el nombre del bloque. Pulsa / y escribe el nombre del bloque, por ejemplo, /verticalsplit, lo que filtrará el bloque que quieres usar.

La tercera opción es usar paréntesis y el nombre del bloque — por ejemplo (api) — lo cual agregará el bloque de endpoint API.

Los hermanos del copiar y pegar de la vieja escuela. ¿Pero por qué cubrir este? Como el editor de Archbee admite Markdown, si deseas pegar en este formato, podrías recibir el siguiente mensaje:

Si haces clic en el botón cancelar, el contenido no se representará, y si haces clic en Aceptar en el cuadro de diálogo, convertiremos el Markdown en bloques de Archbee.

Así que tienes un ejemplo de código que se representará como un bloque de editor de código en Archbee.

Copiar y pegar funciona perfectamente, pero si tienes archivos Markdown o Word, ¿por qué no importarlos a un Espacio?

Antes de importar cualquier contenido, asegúrate de hacer clic en el Espacio donde deseas importar los archivos. Acabas de hacer clic en el tipo de archivo que tienes y has ahorrado minutos de copiar y pegar desde otras fuentes.

Cuando se trata de documentar APIs, tienes múltiples opciones.

Digamos que estás utilizando el estándar OpenAPI (anteriormente Swagger). Esto permite una fácil importación y sincronización de los archivos.

Una vez importado en Archbee, el contenido se mostrará en un diseño de 3 columnas que permite una documentación fácil de gestionar.

Ocurre que la documentación está escrita en un repositorio de GitHub, y puedes seguir escribiendo en GitHub y sincronizar el repositorio con un Espacio de Archbee. El beneficio es que puedes publicar ese Espacio en tu dominio personalizado y añadir otros Espacios con información adicional, como referencias de API.

Antes de comenzar con el contenido, da un pequeño paso que marcará la diferencia más adelante. Configura tu subdominio para tener acceso a los entornos de vista previa y producción. Ve a la página de documentación y sigue los pasos para añadir tu dominio personalizado.

Múltiples opciones están disponibles en la pestaña General - puedes desactivar la opción Indexable por motores de búsqueda (si es público) desde la misma Configuración del Espacio. A menudo quieres mantenerlo activado para que los usuarios encuentren tu sitio en la página de resultados del motor de búsqueda. Puedes ir a la opción de control de acceso público y elegir cualquiera de las cinco opciones para obtener más control.

Antes de escribir cualquier documentación, considera los temas principales que cubrirás. Esta vez un bolígrafo y papel pueden ayudarte a dibujar la estructura.

Luego, crea un documento, conviértelo en una categoría y asígnale un nombre.

Una vez que tengas esto, estarás listo para agregar documentos bajo cada categoría.

Comienza con un documento que presente las cosas principales que un usuario encontrará en el sitio de documentación. No tiene que ser complicado; así es como lo hicimos en nuestra Guía de Usuario y Desarrollador:

Cuando empiezas a añadir contenido, es esencial tener un flujo de trabajo. Aquí tienes uno posible, pero es posible que quieras adaptarlo:

Trabajar con plantillas facilita que los colaboradores comiencen a escribir contenido. Puedes guardar un conjunto de plantillas para ayudarte a iniciar la producción de contenido. Si necesitas inspiración, cuando crees un nuevo documento, verás un botón llamado: Comenzar con una plantilla en la parte inferior de la página. Para crear tus propias plantillas, ve a la navegación en el lado izquierdo, Plantillas, y comienza a crear documentos con la estructura que tus documentos necesitan.

También puedes introducir los bloques personalizados que un autor utilizará o agregar ejemplos de otras fuentes.

Estas opciones están a nivel de documento. Así que debes hacer clic en los tres puntos ⋮ en la parte superior derecha y elegir Controles de Meta SEO.

Agrega un título relevante, cambia la URL, escribe una meta descripción o sube una imagen para las vistas previas.

En la pestaña Apariencia, encontrarás las opciones de personalización como Color de Acento, Logo, y Favicon, junto con otras opciones para la plantilla.

Dependiendo del tipo de productos o servicios, es posible que quieras tener diferentes rutas de URL para los Espacios.

Puedes tener un Espacio como documentación principal y crear diferentes Espacios para otros productos o incluso para sus versiones.

¡Hay un atajo! Puedes crear un clon de cualquier Espacio si los cambios son incrementales. Esto te ayudará a mantener la estructura y hacer las ediciones para la nueva versión.

Así que, si necesitas versionado y múltiples productos, utiliza diferentes Espacios y añádeles la ruta relevante o un dominio personalizado.

Ir a Enlaces de espacio y comienza a construir tu navegación.

El objetivo principal de la página de inicio es ayudar al visitante a ir a la siguiente página.

Crear una página de aterrizaje para tu sitio web de documentación no tiene que seguir las mismas prácticas que un sitio web de presentación.

La primera página del documento es importante para presentar tu producto o servicio a los usuarios, así que mantenerla breve y establecer expectativas ayuda mucho.

Puedes usar la Página de inicio personalizada y agregar tu propio HTML para tener más control sobre la primera página. Hay muchas opciones de las cuales obtener inspiración, y si deseas cambiar el aspecto y la sensación de la primera página, esta es tu opción.

Aquí se muestra cómo uno de nuestros clientes construyó su página inicial para su página de ayuda.

Usa CSS personalizado si quieres agregar tu propio toque al sitio de documentación. Si estás familiarizado con las clases CSS, encontrarás algunos puntos de partida y podrás apuntar a ellos.