VuePress: documentación simplificada

Cuando se trata de cualquier proyecto que requiera alguna interacción del usuario (por ejemplo, usuarios finales, mantenedores, etc.), hay un factor crítico que marca la diferencia entre el éxito y el fracaso: una buena documentación. Esto es cierto independientemente de cuán pequeño o grande sea su proyecto. Después de todo, aparte de brindar soporte personalizado para su proyecto, la documentación es la primera línea de defensa para los usuarios que intentan resolver un problema. Y te guste o no, nunca escucharás a los usuarios que se dan por vencidos después de no poder resolver su problema debido a una documentación inadecuada.

Los desafíos de crear una buena documentación

Cuando se trata de escribir una buena documentación, hay cuatro problemas recurrentes que los equipos suelen encontrar:

1. La documentación a menudo está desactualizada.
   Si bien la falta de documentación para un proyecto puede ser una experiencia frustrante, podría decirse que es peor tener documentación desactualizada . Después de todo, el propósito de tener documentación es proporcionar a los usuarios un cuerpo oficial de conocimiento en el que puedan confiar. Cuando está desactualizado, los usuarios pierden el tiempo y, en última instancia, pierden la confianza en su producto.
   
   La razón principal por la que la documentación se vuelve obsoleta es que el mantenimiento de la documentación es independiente de los cambios de código . Sin invertir mucho tiempo y energía, esto puede ser difícil de resolver porque:
   
   1. La documentación generalmente vive en un servicio de terceros como Confluence o Wiki,
   2. Los desarrolladores suelen estar más interesados ​​en escribir código que en documentación.
2. Los usuarios no pueden proporcionar comentarios fácilmente.
   No importa cuán buena crea que es su documentación, en última instancia, no tiene sentido sin probarla con usuarios reales que puedan proporcionar comentarios. Como se mencionó anteriormente, un sesgo común al evaluar la efectividad de cosas como la documentación es no tener en cuenta a los usuarios que no pudieron resolver sus problemas y se dieron por vencidos. Dado que ningún equipo podría dar cuenta de todos los escenarios de cómo los usuarios podrían usar su producto, los usuarios deben tener una manera fácil y confiable de dar su opinión.
3. La documentación a menudo es escrita por usuarios avanzados para usuarios avanzados.
   La falla con el uso de herramientas estándar como wikis o archivos README es que a menudo solo atienden a un conjunto específico de usuarios que a menudo tienen un conocimiento preexistente de la biblioteca y/o la pila de tecnología. Como resultado, les resulta bastante sencillo navegar por el espacio y encontrar lo que necesitan. Sin embargo, los nuevos usuarios carecen de este conocimiento previo y, por lo tanto, a menudo requieren una experiencia mucho más inmersiva para involucrarlos.
   
   Ejemplos de esto incluyen:
   
   • Un sitio web bien diseñado,
   • capacidad de búsqueda,
   • Navegación lateral guiada,
   • Metainformación fácilmente identificable (es decir, fecha de última actualización),
   • Contenido inmersivo que se extiende más allá de una pared de texto que es difícil de comprender fácilmente.
4. Infraestructura deficiente que dificulta el mantenimiento de la documentación.
   Como si escribir una buena documentación que los usuarios puedan entender no fuera lo suficientemente difícil, la facilidad con la que un desarrollador puede escribir y/o mantener la documentación es fundamental para su viabilidad a largo plazo. Por lo tanto, por cada barrera adicional que los desarrolladores deben enfrentar para escribir y/o mantener la documentación, es más probable que finalmente falle. Como resultado, es fundamental que la experiencia de creación y el mantenimiento de cualquier documentación sean lo más fluidos y atractivos posible.

Si tan solo hubiera una herramienta que pudiera hacer todas estas cosas por nosotros...

Introduzca VuePress

Cuando se escucha por primera vez de VuePress, uno podría estar tentado a adivinar que es una fusión de Vue.js y WordPress. En cambio, deberías pensar en VuePress como:

Vue.js + Imprenta

Porque cuando todo está dicho y hecho, ¡VuePress es un generador de sitios estáticos!

Algunos de ustedes podrían estar pensando, “Espera. ¿Otro generador de sitios estáticos? ¿Cual es el problema?"

Si bien hay una serie de herramientas que son generadores de sitios estáticos, VuePress se destaca entre el paquete por una sola razón: su directiva principal es facilitar a los desarrolladores la creación y el mantenimiento de una excelente documentación para sus proyectos.

¿Por qué VuePress es tan poderoso para crear documentación?

La respuesta es simple. Fue diseñado con un objetivo en mente: ayudar a los desarrolladores a crear excelentes sitios de documentación mientras se mantiene una experiencia de creación divertida. Esto significa que proporciona un marco para que los desarrolladores:

• Cree hermosos sitios de documentación,
• Vienen con características preconstruidas esenciales para todos los sitios de documentación,
• Optimice la experiencia de creación para que sea tan simple como actualizar un archivo Markdown.

VuePress puede coexistir con su base de código existente

Esta es una de las principales razones por las que lo recomiendo encarecidamente. Cuando se trata de mantener la documentación, una forma de garantizar que quedará obsoleta es dificultar que los desarrolladores actualicen los documentos al escribir el código. Si dificulta la experiencia de creación al obligar a los desarrolladores a actualizar las cosas en dos lugares diferentes, esto causará mucha fricción y, a menudo, hará que la documentación se deje de lado. Esto se ve comúnmente cuando los desarrolladores tienen que mantener una herramienta de terceros como un wiki, además del propio código base.

Debido a que es un generador de sitios estáticos, esto significa que puede vivir exactamente en el mismo repositorio que su código.

Como puede ver en esta estructura de aplicación web de muestra, su código viviría en el directorio src de manera normal, pero simplemente tendría un directorio docs para contener toda su documentación. Esto significa que usted obtiene los beneficios de:

• Toda la documentación ahora está controlada por versiones;
• Las solicitudes de extracción ahora pueden contener tanto documentación como cambios de código;
• Crear scripts separados para ejecutar instancias locales de su código y documentos al mismo tiempo;
• Utilice canalizaciones de compilación para determinar si las nuevas implementaciones del sitio de documentación se sincronizan con las implementaciones de código o no.

El tema predeterminado viene con una configuración estándar

Escribir documentación ya es bastante difícil, por lo que VuePress descarga muchas de las decisiones que uno normalmente tiene que tomar y tiene un montón de valores predeterminados incorporados para facilitar su experiencia de creación:

• La escritura de contenido se realiza principalmente con Markdown.
  Esto significa que puede aprovechar su conocimiento existente de la sintaxis de Markdown para diseñar y dar formato a su texto.

• Resaltado de sintaxis de código.
  Si estuviera creando un sitio por su cuenta, necesitaría luchar con las bibliotecas de resaltado de sintaxis de color. Pero tiene suerte porque puede agregar bloques de código en VuePress es muy fácil ya que todo está listo para funcionar sin configuración.

• Materia preliminar para definir metadatos a nivel de página.
  Aunque esté creando en un archivo Markdown, puede usar material preliminar (como YAML, JSON o TOML) para definir metadatos para su página para que sea aún más fácil administrar su contenido.

 --- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---

• Contenedores Markdown personalizados.
  En caso de que no lo supiera, Markdown tiene extensiones para agregar accesos directos aún más útiles para crear hermosos componentes de interfaz de usuario como contenedores personalizados. Y dado que son tan útiles en la documentación, VuePress ya lo configuró para que pueda usarlo de inmediato:

Funcionalidad de búsqueda incorporada

Seamos sinceros. No importa cuánto tiempo dediquemos a escribir una excelente documentación, en última instancia será inútil si los usuarios no pueden encontrarla. En general, hay dos enfoques para esto:

1. Espere a que los robots de los motores de búsqueda rastreen lentamente su sitio con la esperanza de que algún día sus usuarios puedan encontrar la página correcta en su sitio. No es una gran solución.
2. Cree su propia funcionalidad de búsqueda, pero esto puede ser difícil de implementar para sitios estáticos, ya que no se ejecuta ningún código del lado del servidor para crear índices de búsqueda y realizar búsquedas. Sin mencionar que esto le quita tiempo de desarrollo al producto en sí. Así que esto tampoco es genial.

¡Afortunadamente para nosotros, VuePress está aquí para salvar el día una vez más!

VuePress viene con una funcionalidad de búsqueda integrada que genera su propio "motor de búsqueda": leyó bien. Sin ninguna configuración o configuración de base de datos adicional, VuePress está configurado para raspar todos sus documentos para generar un motor de búsqueda simple que mostrará todos sus h1 y h2 a su usuario.

Ahora, algunos de ustedes pueden estar pensando,

"¿Qué pasa si quiero algo que proporcione una indexación de nivel inferior para la búsqueda?"

Bueno, VuePress también lo tiene cubierto allí porque está diseñado para integrarse fácilmente con Algolia DocSearch, que puede proporcionarle esa funcionalidad de forma gratuita si cumple con sus requisitos:

La navegación de la barra lateral es tan simple como activar o desactivar la función

Cualquiera que haya sido responsable de administrar contenido, sabe lo complicado que puede ser crear una barra lateral que tenga elementos anidados y luego rastrear en qué posición se encuentra el lector mientras se desplaza hacia abajo. Entonces, ¿por qué dedicar tiempo a eso cuando podría estar escribiendo mejores documentos? Con VuePress, la barra lateral es tan simple como cambiar la portada de una página:

Generación automática de metadatos importantes que comúnmente se pasan por alto

Una de las cosas más frustrantes que un usuario puede encontrar es la documentación desactualizada. Cuando un usuario sigue los pasos y tiene problemas para comprender por qué algo no funciona, poder averiguar fácilmente la fecha de la última actualización puede ser increíblemente útil tanto para el usuario como para los encargados del mantenimiento del proyecto.

Con una configuración simple, VuePress puede garantizar la salida automática de la última fecha de actualización en la página para que sus usuarios siempre sepan cuándo fue la última vez que se actualizó.

Además de eso, con un poco de configuración, VuePress también hace que sea increíblemente fácil para los usuarios contribuir a sus documentos al generar automáticamente un enlace en la parte inferior de cada página que permite a los usuarios crear fácilmente una solicitud de extracción para sus documentos.

No hay nada más fácil que eso para sus usuarios.

Implementación en cualquier sitio de alojamiento estático

Dado que VuePress es un generador de sitios estáticos en esencia, esto significa que puede implementarlo en cualquier plataforma de alojamiento popular, como:

• netlizar
• Páginas de GitHub
• Páginas de GitLab
• Heroku
• Ahora

¡Todo lo que necesita hacer para construir el sitio es ejecutar vuepress build {{ docsDir }} con el lugar donde vive su directorio y tendrá todo lo que necesita para implementarlo en vivo en la web!

Nota : Para obtener guías más detalladas sobre cómo hacer esto, consulte las guías oficiales de implementación de VuePress.

Aprovechar Vue dentro de su archivo Markdown

Sé que sé. ¿Podemos usar Vue.js en nuestro Markdown? ¡Sí, lo leiste bien! Si bien es técnicamente opcional, este es probablemente uno de los aspectos más emocionantes de VuePress porque le permite mejorar su contenido de Markdown como nunca antes.

Defina datos repetitivos en un solo lugar y actualícelos en todas partes con interpolación

En el siguiente ejemplo, verá un breve ejemplo de cómo puede aprovechar las variables locales (como las definidas en el frontmatter), así como las definidas globalmente (como el título del sitio):

 --- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!

Usar componentes de Vue dentro de Markdown

Le daré un momento para que se recupere después de leer esto, pero sí, ¡los componentes Vue en vivo con una instancia completa de Vue pueden ser suyos si lo desea! Tomará un poco más de trabajo configurarlo, pero esto es de esperar ya que está creando contenido personalizado que se ejecutará en su documentación.

Aquí hay un ejemplo rápido de cómo se vería un componente Counter en un archivo Markdown:

Esta es quizás la parte más poderosa de la personalización disponible para la documentación, ya que significa que ahora tiene la libertad de crear contenido personalizado que se extiende mucho más allá de las capacidades de Markdown estándar. Entonces, ya sea que proporcione una demostración o algún código interactivo, ¡las ideas son infinitas!

Próximos pasos

Si desea configurar un hermoso sitio de documentación para que sus usuarios aprendan a usar su producto, no hay nada más fácil que VuePress. Y aunque puede ser fácil suponer que VuePress solo debe ser utilizado por proyectos que usan Vue.js, esto no podría estar más lejos de la verdad. Estos son solo algunos ejemplos de los diferentes tipos de proyectos que aprovechan VuePress para sus sitios de documentación:

• CMS artesanal
• UmiJS (que está construido para React)
• abrirHAB
• Pavo real

Al final del día, independientemente de si usa VuePress o no, espero que esto lo haya ayudado a inspirarse para crear una mejor documentación para sus usuarios.

Más recursos

Hay muchas cosas interesantes que no cubrí aquí en este artículo (por ejemplo, creación de temas, blogs, etc.), pero si desea obtener más información, consulte estos recursos:

• Documentos oficiales de VuePress
• Una lista seleccionada de recursos relacionados con VuePress
• Galería VuePress
• Blog de VuePress estándar