Unlimited Wordpress themes, plugins, graphics & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Web Design
  2. Documentation
Webdesign

Documentando tus Proyectos con Daux.io

by
Length:LongLanguages:

Spanish (Español) translation by James Kolce (you can also view the original English article)

Final product image
What You'll Be Creating

Documentar un proyecto puede ser una molestia, pero no tiene que ser así. Existen varias herramientas para hacer el trabajo, yo a menudo uso Daux.io por su flexibilidad.

En este artículo, te mostraré por qué deberías de documentar, cómo puedes obtener Daux.io y cómo puedes comenzar a usarlo ahora mismo para hacer tus projects mucho mejores.

Por Qué la Documentación es Necesaria

Escribir documentación para tu proyecto podría ser una de las decisiones mas importantes que hagas. La razón por la cual esto suele pasarse por alto para proyectos basados en web es que no hay mucho en juego.

Tomemos por ejemplo un Boeing 787. Este producto tiene un cuerpo extenso de documentación, respaldando todos los aspectos desde diseño hasta mantenimiento. Incluso hay un manual de casi 150 páginas documentando las 787 características a tener en cuenta al planificar aeropuertos.

¿Por qué debería tener un avión una amplia documentación mientras que un sitio web no?

Creo que hay tres razones principales:

  • Hay mucho más dinero en juego
  • Preocupaciones de seguridad
  • Cuestiones de escala

Sitios web rara vez tienen problemas de seguridad, pero tan pronto como la escala o el dinero asoman su cabeza, puede estar seguro de que la documentación se abrirá. Todos los proyectos grandes como Twitter y Facebook tienen asombrosas cantidades de información disponible para los desarrolladores, internos y terceros por igual.

Sitios web que generan una gran cantidad de ingresos a menudo también deciden crear una buena documentación. La idea es que si algo necesita modificarse, todo el mundo puede hacer referencia a la documentación y así el sitio web es mucho menos probable que pierda dinero debido a la pérdida de disponibilidad.

¿Esto significa que puedes pasar sin documentación para un proyecto más pequeño? Seguro que sí, la pregunta es: ¿deberías?

Los Beneficios de la Documentación

La documentación proporciona un marco común de referencia para un proyecto. El beneficio de esto es bastante obvio cuando se trabaja en un equipo pero se pasa por alto cuando alguien está trabajando solo.

Si haces tu vida con la construcción de sitios web, las posibilidades son que construyas al menos unos cuantos al año. ¿Recordarás cómo un sitio web construido en Enero auto-tweetea su contenido si lo llegaras a mirar él próximo mes de Agosto? ¿Qué pasa si una empresa te pide que entregues un proyecto a otro desarrollador? Podrías pasar una hora cada mañana respondiendo preguntas sobre el código durante todo el próximo mes.

Includo el programador mas consistente es inconsistente. Mientras crecemos y aprendemos, tendemos a modificar nuestra forma de que trabajar. Quizás has introducido una herramienta de construcción como Gulp en tu flujo de trabajo, tal vez has comenzado a usar PHP orientado a objetos.

La documentación puede también explicar situaciones que no son obvias en el propio código. Puedes haber elegido una solución mediocre a propósito, simplemente porque pidieron hacer algo rápidamente y el fin justificó los medios. Esto se puede agregar a la documentación, tal vez como una tarea para actualizar más adelante.

Documentación con Daux.io

Daux.IO puede asustar a algunas personas al principio porque no es simple HTML, sólo se puede previsualizar usando un servidor. Sin embargo, configurar todo es bastante sencillo y una vez que saltes ese obstáculo, su uso es fácil y flexible.

Conseguir Daux.io

La forma más fácil de obtener Daux.io es descargarlo desde Github. Puedes descargar el paquete mediante el botón Descargar ZIP en la barra lateral derecha. Si eres un usuario experimentado de Github puedes clonarlo, o incluso puedes tomarlo de Packagist a través de compositor.

Si lo descargas desde Github terminarás con una carpeta llamada "daux.io-master".

Renombralo a "documentación" y muévelo al escritorio para claridad. Para escribir la documentación realmente no necesitas nada. Puedes editar los archivos Markdown en cualquier editor y utilizar un comando para convertirlo a HTML, para compartirlo fácilmente. Sin embargo, lo mejor es previsualizar nuestro trabajo a medida que avanzamos, así que vamos a hacer alguna preparación para ello.

Vista Previa de la Documentación

Para previsualizar la documentación necesitaremos un servidor. Por suerte, todo está siempre dentro de la carpeta Daux.io del proyecto, solo necesitamos los requisitos previos para ejecutar el servidor: NPM y Grunt.

Instalando NPM y Grunt

La forma más fácil de obtener NPM (Node Package Manager) es instalando Node. Ve al sitio web de Node y descarga al instalador. Una vez instalado, deberías de poder usar el comando npm en la terminal (en Linux/OS X) o en el símbolo del sistema (Windows).

Nota rápida: Me referiré al símbolo de sistema en Windows y a la terminal en Linux/OS X con la misma palabra: terminal.

La próxima cosa que necesitarás es Grunt. Grunt es instalado mediante NPM así que si ya has completado el último paso debería de ser super sencillo. Abre la terminal y escribe el siguiente comando:

Ahora tienes las herramientas de base necesarias para empezar. Si eres nuevo en npm recomiendo aprender más sobre él. Permite instalar fácilmente herramientas y no necesariamente necesitas saber Node.js para utilizar herramientas de trabajo con npm (como Grunt).

Todo hasta este punto sólo es necesario si no tienes estas herramientas instaladas. No importa cuántas instancias de documentaciones de Daux.io tengas, no tendrás que hacer esto otra vez.

Consejo: Aprende más acerca de las herramientas de línea de comandos siguiendo la serie para principiantes La Linea de Comandos para Diseño Web por Kezz Bracey.

Usuarios de Windows: Instalando PHP

Este paso es sólo para usuarios de Windows. OS X y la mayoría distribuciones de Linux vienen con PHP instalado así que si estás en esas plataformas puedes omitir esta sección. Lamentablemente instalar la línea de comandos PHP en Windows es un poco de molestia, aquí está el proceso.

Diríjase a la página de descargas PHP y toma la versión de PHP que quieras. Yo usé la versión "VC11 x86 Non Thread Safe" cuando estuve probando. He descargado y descomprimido este archivo en mi carpeta raíz C:/ y renombré la carpeta resultante a "php". Al final del proceso debes tener una carpeta con el nombre "php" en tu directorio principal C:/, la carpeta debe contener un "php.exe" en algún lugar.

A continuación, necesitaremos asegurarnos de que el comando PHP se puede ejecutar desde cualquier lugar. En Windows 7, la forma más sencilla de hacerlo es ir al menú Inicio, haga clic derecho sobre Equipo y seleccione Propiedades. Haga clic en Configuración Avanzada del Sistema en la barra lateral izquierda. Haga clic en la ficha Opciones Avanzadas, luego sobre el botón Variables de Entorno en la parte inferior.

Editing path on Windows

Tendrás que hacer clic en ruta en el panel superior y después editar. Al final del valor, agregue una referencia de carpeta, algo como esto: "C:\Users\Dani\environment". Esta debe ser una carpeta dentro de tu propia carpeta de usuario. Una vez hecho esto, guarda todo y crea esta carpeta. (Si utilizas una versión diferente de Windows echa un vistazo en Computerhope, muestra cómo hacer esto en varias versiones).

Dentro de esta carpeta crea un archivo llamado "phppath.cmd". Edita este archivo usando cualquier editor de texto y agrega el siguiente contenido:

Una vez hecho esto, ve a esta carpeta mediante el símbolo del sistema escribiendo cd %userprofile%/environment y ejecute¡a el siguiente comando: phppath.

Finalmente, cierra el símbolo del sistema y vuélvelo a abrir, php ahora debe estar disponible a nivel global. Una vez más, esto es algo que sólo tienes que hacer una vez y sólo en Windows.

Configuración de Daux.io

Todavía en tu terminal, ve a la carpeta de proyecto. Recuerda que esto debe estar en nuestro escritorio en esta etapa. En Windows puedes usar el siguiente comando para obtener la carpeta del proyecto:

En OS X se puede utilizar el siguiente comando:

El primer comando que debes ejecutar es npm install. Una vez que ha finalizado ejecuta npm update para asegurarte de que todo está actualizado. Estos comandos instalan y actualizan todas las dependencias de Daux.io Necesitarás hacer esto para cada instancia de Daux.io que tengas.

Ejecutando la Vista Previa

Estamos finalmente listos para previsualizar nuestra documentación. Ahora se trata de un comando, todo lo que necesitas hacer es escribir grunt en la terminal (Asegúrate de que está en la carpeta de documentación cuando ejecutes el comando).

Después de unos segundos de pensar deberías ver algo como esto:

Running Grunt with Dauxio

Esto significa que el servidor está arriba y funcionando, una nueva pestaña puede ya estar abierta en tu navegador. Si no, echa un vistazo a la IP que se muestra junto a "Escuchar en" en la terminal e ingrésala en tu navegador. En mi ejemplo esta IP es "127.0.0.1:8085".

Nota: en algunos casos la pestaña se abre pero muestra "no se encuentra la pagina" o un error similar. En este caso, regarla la pestaña después de un par de segundos, el servidor puede necesitar un poco más tiempo para inicializar.

Ahora debes de ver la documentación por defecto en el navegador. La vista que estamos viendo es generada de forma ad hoc de los archivos Markdown de documentación. Ahora que podemos ver lo que estamos haciendo, vamos a ver la escritura de la documentación.

Escribiendo la Documentación

Dentro de la carpeta "documentación" se debe ver una carpeta "docs". Esta contiene la documentación, todo lo demás es para que Daux.io haga su magia. Daux.IO utiliza una convención de nomenclatura específica para darte el control total sobre el orden de las páginas.

Cada elemento de esta página debe comenzar con un número y un guión bajo. Cuanto mayor sea el número más abajo en la página estará en la documentación. Si necesitas una sola página crea un archivo Markdown (por ejemplo: 04_Updating_Plugins), si necesitas una estructura jerárquica de páginas, crea una carpeta (por ejemplo: 05_Code_Styling).

El texto después del número determina el nombre de la página en la documentación. Mis ejemplos anteriores se convertirán en "Actualización de Plugins" y "Estilo de Código". Asegúrate de utilizar sólo caracteres alfanuméricos y guiones bajos, los guiones bajos se convertirán en espacios.

Folder names and sections in Dauxio

A partir de aquí es suave, todo lo que necesitas hacer es editar los archivos en estilo Markdown. Si no estás familiarizado con Markdown mira el Cheatsheet de Markdown. Es esencialmente una forma de marcar texto (indicar títulos, enlaces, imágenes, etc.) sin código HTML.

Si estás creando una sección con subpáginas, usando una carpeta puedes especificar subpáginas de la misma manera que antes. Dentro de la carpeta creada, crea archivos individuales a partir de un número (que da orden a la página) el nombre que quieres que aparezca.

Páginas de Inicio

Otra cosa interesante que Daux.io te permite hacer es crear una página de inicio para tus secciones. Toda la documentación puede obtener una página de inicio si se crea un "_index.md" archivo. Echa un vistazo al ejemplo por defecto para tener una idea del formato.

Dauxio landing page

Cada sección puede también tener una página de inicio. Si una sección no tiene una página de inicio, el elemento del menu superior no será cliqueable a ningún lugar, solo abre la lista de subsecciones. Si quieres que la entrada superior renga su propia página, crea un "index.md" archivo dentro de la carpeta de la sección.

Administrar Documentaciones Múltiples

Algunos proyectos pueden requerir múltiples documentaciones. Un sitio web puede contener una documentación de usuario final y una documentación para el desarrollador, que contendría información completamente diferente.

Una forma de manejar necesidades de múltiples documentaciones como esta es crear multiples instancias de Daux.io. Sin embargo, esto requiere ejecutar el servidor por separado y configurar algunas cosas más. Por suerte, ¡hay una mejor forma!

Echa un vistazo a "global.json" archivo en la carpeta de documentación principal. Si abres esto con su editor de texto verás que el parámetro docs_directory se establece en docs. Crear una copia del directorio docs, asígnale el nombre "user_docs" y añadir algunos archivos dummy diferentes para diferenciarlos de la documentación original.

Ahora cambia el parámetro docs_directory a user_docs y recarga la documentación en tu navegador. Ahora estás viendo el contenido de la carpeta nueva. Esto facilita cambiar hacia adelante y hacia atrás entre las documentaciones sobre la marcha, sin tener que reiniciar el servidor o utilizar una instancia distinta de Daux.io.

Generación de Documentación Final

Por supuesto, al final del día tenemos que distribuir nuestra documentación. Se recomienda hacerlo en forma HTML y Daux.io nos tiene cubierto! En la terminal, en el directorio principal de tu documentación, ejecuta el siguiente comando:

Esto creará una carpeta "static" con todos los archivos HTML y activos necesarios para ver la documentación. Puede comprimir esta carpeta y enviar a alguien o subirla a un servidor y un enlazarla.

Configuración Avanzada de Proyectos

Hay un montón de cosas que puedes controlar a través de "default.json" archivo. Por defecto habrá un enlace Hecho por Todaymade en la barra lateral junto con algunos enlaces de Twitter que no necesitas o querrás personalizar en tu proyecto. La Página principal de Daux.io muestra las opciones que puedes usar debajo de "Configuración" más abajo en la página. o sólo ve a "default.json" archivo.

Puedes utilizar "twitter": ["yourtwittername"] para agregar tu propio enlace de Twitter, por ejemplo. Los enlaces pueden ser controlados utilizando el parámetro enlaces, aquí está cómo agregar un par:

Puedes encontrar todas las opciones en la Página principal de Daux.io. Este es un ejemplo de un completo "default.json" archivo para un proyecto imaginario.

Conclusión

La configuración de Daux.io puede parecer una tarea desalentadora al principio, pero no es tan largo, especialmente en sistemas Mac/Linux donde la mayor parte de lo que necesitamos está preinstalado. Si no estás acostumbrado a la terminal y servidores locales puede tomar un poco mientras te acostumbras al entorno pero al hacerlo pagará diez veces.

Una vez que estés arriba y corriendo con Daux.io encontrarás que es fácil de usar, flexible y fácil de mantener. Su proyecto, tu cliente, tus compañeros de trabajo y los usuarios finales del proyecto te agradecerán por tus esfuerzos y con suerte se reducirá el tiempo que pasas dado soporte al proyecto.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.