Crear un sitio web de documentación

La documentación viene en muchas formas y formatos. Es posible que ya tenga algunos recursos o que necesite comenzar desde cero. Veamos cómo agregar contenido con Archbee.

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

Los bloques personalizados le ayudan a formatear el contenido según lo necesite. Para abrirlos, escriba una barra diagonal / en el editor y revise las opciones.

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

Por ejemplo, si desea vincular dinámicamente a otros documentos, escriba @ y el título del documento. Esto se conectará al id del documento. Si cambia el título o la posición del documento, el enlace siempre apuntará a él.

Otro ejemplo es llamar por su nombre al bloque. Presione / y escriba el nombre del bloque, por ejemplo, /verticalsplit, lo que filtrará el bloque que desea usar.

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

Los hermanos de copiar-pegar de la vieja escuela. Pero ¿por qué cubrir este caso? Dado que el editor de Archbee soporta Markdown, si desea pegar en este formato, podría obtener el siguiente mensaje:

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

Así, tendrá un ejemplo de código que se procesará como un bloque de editor de código en Archbee.

Copiar y pegar funciona bien, pero si tiene archivos Markdown o Word, ¿por qué no importarlos a un Space?

Antes de importar cualquier contenido, asegúrese de hacer clic en el Space donde desea importar los archivos. Solo tuvo que hacer clic en el tipo de archivo que tiene y ahorró minutos de copiar-pegar desde otras fuentes.

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

Supongamos que está utilizando el estándar OpenAPI (anteriormente Swagger). Esto permite una importación y sincronización sencilla de los archivos.

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

Sucede que la documentación está escrita en un repositorio GitHub, y puede continuar escribiendo ahí y sincronizar el repositorio con un Space de Archbee. El beneficio es que puede publicar ese Space en su dominio personalizado y agregar otros Spaces con información adicional como referencias API.

Antes de comenzar con el contenido, dé un pequeño paso que marcará la diferencia más adelante. Configure su subdominio para tener acceso a los entornos de vista previa y producción. Vaya a la página de documentación y siga los pasos para agregar su dominio personalizado.

Existen múltiples opciones disponibles en la pestaña General - puede desactivar Indexable por motores de búsqueda (si es público) desde las mismas Configuraciones del Space. A menudo desea esto activado para que los usuarios encuentren su sitio en la página de resultados del motor de búsqueda. Puede ir a la opción de control de acceso público y elegir cualquiera de las cinco opciones para tener más control.

Antes de escribir cualquier documentación, considere los temas principales que cubrirá. Esta vez un bolígrafo y papel podrían ayudarle a dibujar la estructura.

A continuación, cree un documento, conviértalo en una categoría y asígnele un nombre.

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

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

Cuando comience a agregar contenido, es esencial tener un flujo de trabajo. Aquí hay uno posible, pero podría querer adaptarlo:

Trabajar con plantillas facilita que los colaboradores comiencen a escribir contenido. Puede guardar un conjunto de plantillas para ayudarle a iniciar la producción de contenido. Si necesita inspiración, cuando cree un nuevo documento, verá un botón llamado: Comenzar con una plantilla en la parte inferior de la página. Para crear sus propias plantillas, vaya a la navegación en el lado izquierdo, Templates, y comience a crear documentos con la estructura que necesitan sus documentos.

También puede presentar los bloques personalizados que un autor usará o agregar ejemplos de otras fuentes.

Estas opciones están a nivel de documento. Entonces debe hacer clic en los tres puntos ⋮ en la parte superior derecha y seleccionar Controles meta de SEO.

Agregue un título relevante, cambie la URL, escriba una meta descripción o cargar una imagen para las vistas previas.

En la pestaña Apariencia encontrará las opciones de marca como Color de acento, Logotipo, y Favicon, junto con otras opciones para la plantilla.

Dependiendo del tipo de productos o servicios, es posible que desee tener diferentes rutas de URL de Space.

Puede tener un Space como la documentación principal y crear diferentes Spaces para otros productos o incluso para sus versiones.

¡Hay un atajo! Puede crear un clon de cualquier Space si los cambios son incrementales. Esto le ayudará a mantener la estructura y realizar las ediciones para la nueva versión.

Así que si necesita versionado y multiproducto, use Spaces diferentes y añádales la ruta correspondiente o un dominio personalizado.

Vaya a Space links y comience a crear su 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 su sitio de documentación no tiene que seguir las mismas prácticas que un sitio de presentación.

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

Puede usar la función Página de aterrizaje personalizada y añadir su HTML para tener más control sobre la primera página. Hay muchas opciones de inspiración, y si quiere cambiar el aspecto y la sensación de la primera página, esta es su opción.

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

Use CSS personalizado si desea añadir su propio toque al sitio de documentación. Si está familiarizado con clases CSS, encontrará algunas para comenzar y podrá apuntar a ellas.