Notation

Notation es una potente herramienta de interfaz de línea de comandos (CLI) diseñada para desarrolladores que desean mantener su documentación junto con su código. Cierra la brecha entre escribir documentación en un formato simple y universal como Markdown y publicarla en una plataforma versátil y colaborativa como Notion. La filosofía central detrás de Notation es que la documentación debe vivir con el código que describe, estar sujeta a los mismos procesos de revisión y ser fácil de actualizar sin iniciar sesión en servicios separados. Elimina la complejidad de gestionar sitios web de documentación separados o lidiar con frameworks de frontend, ofreciendo un flujo de trabajo simplificado y centrado en el desarrollador.

Al usar Notation, los equipos pueden asegurarse de que su documentación esté siempre actualizada con su base de código. Cuando se fusiona el código, la documentación correspondiente se puede publicar en Notion con un solo comando. Esto hace que la documentación sea accesible no solo para otros ingenieros, sino también para miembros del equipo no técnicos como gerentes de producto, diseñadores y personal de soporte que se sienten cómodos usando Notion. La herramienta aprovecha todas las características nativas de Notion, incluida su potente búsqueda, capacidades de IA, formato enriquecido y opciones flexibles para compartir, proporcionando un sistema de documentación robusto de forma gratuita.

Cómo usar Notation

Usar Notation implica un proceso de configuración sencillo que integra tu entorno de desarrollo local con tu espacio de trabajo de Notion:

1. Instalación: Instala el binario de Notation en tu máquina local usando un simple comando curl proporcionado en la documentación oficial. Esto hace que el comando `notation` esté disponible en tu terminal.
2. Configuración: Crea un archivo de configuración llamado `Notation.toml` en el directorio `~/.notation/`. Este archivo almacenará tu secreto de la API de Notion y el nombre de la página principal en Notion donde deseas publicar tu documentación.
3. Integración de Notion: Necesitas crear una nueva integración interna dentro de tu espacio de trabajo de Notion. Esto generará una clave de API secreta que agregarás a tu archivo `Notation.toml`.
4. Conectar a la Página: En Notion, navega a la página que designaste como la página principal. Usa el menú 'Conexiones' para otorgar acceso a esta página a tu integración recién creada.
5. Escribir Documentación: Escribe tu documentación en archivos Markdown dentro del repositorio de tu proyecto. Puedes organizar los archivos en directorios, que Notation convertirá en subpáginas anidadas en Notion.
6. Publicar: Ejecuta el comando `notation ship --src ` en tu terminal. Notation analizará tus archivos Markdown y la estructura de directorios, y luego creará o actualizará automáticamente las páginas correspondientes en tu espacio de trabajo de Notion.

Características principales de Notation

• Conversión de Markdown a Notion: Convierte automáticamente archivos Markdown estándar en páginas de Notion con un formato elegante. Admite encabezados, listas, bloques de código, tablas, enlaces y más.
• Preservación de la Estructura de Directorios: Replica tu estructura de directorios local como páginas anidadas en Notion, facilitando la organización de documentación compleja.
• Flujo de Trabajo Basado en CLI: Se integra perfectamente en el entorno de línea de comandos del desarrollador y se puede agregar a las canalizaciones de CI/CD para actualizaciones de documentación automatizadas.
• Metadatos de Página Personalizados: Te permite establecer el título de la página de Notion y el ícono de emoji directamente desde tu archivo Markdown usando indicadores simples como `--title "Mi Página"` y `--emoji 🚀`.
• Contenido de la Página Principal: Se puede usar un archivo especial `intro.md` para agregar contenido directamente a la página principal, en lugar de crear una subpágina separada.
• Aprovecha el Poder de Notion: Una vez publicada, la documentación se beneficia de la búsqueda avanzada de Notion, las funciones de IA integradas, la edición colaborativa y las opciones flexibles para compartir (interno, público o como un sitio web).
• Manejo de Enlaces Relativos: Convierte inteligentemente los enlaces relativos entre archivos Markdown en enlaces de página de Notion adecuados, asegurando una navegación fluida dentro de tu documentación.

Casos de uso para Notation

Notation es versátil y se puede adaptar a diversas necesidades de documentación:

• Wikis de Ingeniería Internos: Crea y mantén una base de conocimientos centralizada para tu equipo de desarrollo, con la documentación viviendo justo al lado del código relevante.
• Documentación de API Pública: Publica documentación de API clara y bien estructurada para desarrolladores externos. La página de Notion se puede hacer pública con un solo clic.
• Guías y Manuales de Usuario: Desarrolla documentación orientada al usuario que sea fácil de contribuir para escritores no técnicos (a través de Notion) y de actualizar para los desarrolladores (a través de Markdown).
• Documentación de Proyectos: Mantén todos los documentos relacionados con el proyecto, desde especificaciones técnicas hasta notas de reuniones, organizados y sincronizados con el ciclo de vida de desarrollo del proyecto.
• Base de Conocimiento Personal: Los desarrolladores pueden usarlo para gestionar sus notas personales y referencias técnicas, publicándolas en un espacio privado de Notion.

Ventajas de Notation

La principal ventaja de Notation es su simplicidad y su enfoque centrado en el desarrollador.

• Documentación como Código: Al mantener los documentos en el repositorio, se pueden controlar por versiones, revisar y actualizar como parte del flujo de trabajo de desarrollo estándar.
• Reducción de Sobrecarga: Elimina la necesidad de gestionar y desplegar generadores de sitios estáticos complejos como Docusaurus o aprender frameworks de frontend como React.
• Fuente Única de Verdad: Asegura que la documentación en Notion sea un reflejo directo de los archivos Markdown en el repositorio, evitando la deriva de contenido.
• Accesibilidad Mejorada: Hace que la documentación técnica sea fácilmente accesible y legible para los no ingenieros, fomentando una mejor colaboración interfuncional.
• Rentable: La herramienta en sí es gratuita y de código abierto, y aprovecha los niveles gratuitos o existentes de Notion, lo que la convierte в una solución muy económica.

Precios y planes

Notation es una herramienta gratuita y de código abierto. Está disponible para su descarga y uso sin costo. Los usuarios solo están sujetos a los costos asociados con su plan de Notion (muchos casos de uso pueden ser atendidos por el plan gratuito de Notion) o cualquier servicio de terceros que puedan usar para convertir su página de Notion en un sitio web con dominio personalizado, como super.so.