Capítulo 2. Primeros Pasos

Tabla de contenidos

Empezando Con lo Que se Tiene
Escoger un Buen Nombre
Poseer el nombre en los espacios de nombre importantes
Tener los objetivos claros
Declara Que el Proyecto es Libre
Lista de Características y Requerimientos
Estado del Desarrollo
El estado del desarrollo debe reflejar siempre la realidad.
Descargas
Control de versiones y Acceso al Bug Tracker
Canales de Comunicación
Pautas de Desarrollo
Documentación
Disponibilidad de la documentación
Documentación para Desarrolladores
Demos, Capturas de Pantalla, Videos y Ejemplos de Salidas
Hosting
Escogiendo una licencia y Aplicándola
Las licencias "Haz lo que quieras"
La GPL
Cómo aplicar una licencia a nuestro software
Ajustar el tono
Evitar discusiones privadas
Cortar de Raíz la Mala Educación
Practicar Revisiones Visibles del Código
Caso de Estudio
Se abierto desde el primer día
Esperar sólo crea un evento de exposición
Al abrir un proyecto cerrado, hay que ser sensible acerca de la magnitud de los cambios
Anunciando

El clásico modelo de cómo los proyectos de software libre deben iniciar fue propuesto por Eric Raymond, en un artículo ahora famoso sobre procesos de código abierto titulado La catedral y el bazar. Él escribió:

Todos los trabajos buenos en software comienzan tratando de paliar un problema personal de quien los programa

(de catb.org/~esr/writings/cathedral-bazaar/ )

Es de notar que Raymond no estaba diciendo que los proyectos de código abierto no sólo suceden cuando cierto individuo tiene una necesidad. En cambio, nos está diciendo que los buenos programas son resultado de que un programador tenga un interés personal en ver el problema resulto. La relevancia de esto para el software libre ha sido que ésta necesidad personal sea frecuentemente a motivación para iniciar un proyecto de software libre.

Esto sigue siendo la manera cómo muchos de los proyectos de software libre se inician, pero menos ahora que en 1997, cuando Raymond escribió esas palabras. Hoy, tenemos el fenómeno de organizaciones —incluidas corporaciones con fines de lucro, de gobierno, sin fines de lucro, etc—iniciando desde cero, proyectos Open Source centralizados y a gran escala. El desarrollador solitario, tecleando algo de código para resolver un problema local y luego dándose cuenta de que los resultados tienen un mayor aplicación, sigue siendo la fuente de muchos software libre, pero esa no es la única historia.

De todas formas, el objetivo de Raymond sigue siendo profundo. La condición esencial es que los productores de software libre tengan un interés directo en su éxito, usualmente porque ellos mismos lo utilizan o trabajan directamente con personas que lo usan. Si el software no hace lo que se supone debería hacer, la persona u organización que lo han producido sentirán insatisfacción en su labor diaria. Por ejemplo, el software libre desarrollado por la Fundación Kuali (kuali.org), utilizado por instituciones educativas para manejar sus finanzas, becas de investigación, sistemas de recursos humanos, información de estudiantes, etc, poco de esto puede ser considerado como un problema personal de un programador. En particular éste problema surge directamente de la experiencia de las instituciones interesada, por lo cual si el proyecto falla en satisfacerlos, ellos lo sabrán. Este arreglo produce buenos programas porque el bucle de críticas fluye en la dirección correcta. El programa no está siendo escrito para ser vendido a alguien más, es solo para que sean ellos quienes resuelvan sus problemas. Está siendo desarrollado para resolver su propio problema, luego compartiéndolo con todo el mundo como si el problema fuera una enfermedad y el software la medicina, la cual debe ser distribuida para erradicar la epidemia.

Este capítulo trata de cómo introducir un nuevo proyecto de software libre al mundo, pero muchas de sus recomendaciones sonarán familiares a una organización sanitaria distribuyendo medicinas. Los objetivos son muy similares: quieres dejar claro lo que hace la medicina, hacerla llegar a las manos correctas y asegurarte de que aquellos quienes la reciben saben como usarla. Pero con el software, también deseas incitar a algunos de los receptores a unirse al esfuerzo de investigación para mejorar la medicina.

La distribución del software libre es una tarea a dos bandas. El programa necesita usuarios y desarrolladores. Estas dos necesidades no tienen por que estar en conflicto, pero si que añaden cierta complejidad a la presentación inicial de un proyecto. Alguna información es útil para las dos audiencias, alguna sólo lo es para alguna u otra. Ambos tipos de información deben suscribirse al principio de las presentaciones en escala, esto es, el grado de detalle con el que se presenta cada etapa debe corresponder a la cantidad de tiempo y esfuerzo puesto por el lector. Un mayor esfuerzo debe tener siempre una mayor recompensa. Cuando los dos no se relacionan conjuntamente, las personas pueden perder rápidamente su fe y perder el impulso.

El corolario a esto es:las apariencias importan. Los programadores en particular, no desean creer esto. Su amor por la sustancia sobre la forma es casi un punto de orgullo profesional. No es un accidente que tantos desarrolladores exhiban una antipatía hacia los trabajos en marketing y en relaciones públicas o que diseñadores gráficos profesionales usualmente se sientan horrorizados de los diseños que los desarrolladores hacen por su cuenta.

Esto es penoso, ya que hay situaciones en las que la forma es la sustancia y la presentación de proyectos es una de estas. Por ejemplo, lo primero que un visitante descubre sobre un proyecto es como se ve su sitio web. Esta información es absorbida antes de que el contenido en si sea comprendido—antes de que cualquier línea haya sido leída o enlaces pulsados. Aunque parezca injusto, las personas no pueden evitar el formarse una opinión inmediatamente después de la primera impresión. La apariencia del sitio señala si se ha tomado cuidado en la organización de la presentación del proyecto. Los humanos tenemos una antena extremadamente sensible para detectar el empeño en el cuidado. Muchos de nosotros podemos decir con sólo un vistazo si un sitio web ha sido ensamblado rápidamente o ha sido diseñado con cuidado. Ésta es la primera pieza de información que el proyecto muestra y la impresión que cree será asociada al resto del proyecto por asociación.

Aunque mucho de éste capítulo habla acerca del contenido con el que se debería iniciar el proyecto, recuerde que la presentación también importa. Ya que el sitio web debe funcionar para dos tipos diferentes de visitantes—usuarios y desarrolladores— hay que ser directo y conciso. A pesar de que este no es el lugar para un tratado general acerca de diseño web, un principio es suficientemente importante para merecer nuestra atención, particularmente cuando sirve a múltiples audiencias: la gente debe tener una idea de a donde lleva un enlace antes de pulsar en el. Por ejemplo, debe ser obvio que con sólo ver el enlace a la documentación para los usuarios, que les lleve a la documentación para los usuarios, sin mencionar la documentación para los desarrolladores. Dirigir un proyecto se basa parcialmente en suministrar información, pero también en suministrar comodidad. La mera presencia de ofrecer ciertos estándares, en lugares obvios, tranquiliza a usuarios y desarrolladores quienes están decidiendo si desean involucrarse. Dice que este proyecto funciona, ha anticipado las preguntas que la gente puede hacer y ha hecho un esfuerzo en responderlas sin la necesidad del más mínimo esfuerzo por parte del visitante. Al dar ésta aura de preparación, el proyecto envía un mensaje: "Su tiempo no será malgastado si se involucra", lo que es exactamente lo que la gente desea escuchar.

Primero Investiga

Antes de iniciar un proyecto Open Source hay un importante advertencia:

Siempre investiga si existe un proyecto que hace lo que deseas. Las posibilidades son muy buenas de que cualquier problema que desees resolver ahora alguien más lo haya deseado resolver con anterioridad. Si han sido capaces de resolverlo y han liberado bajo una licencia libre entonces hoy, no será necesario inventar la rueda. Existen excepciones claro: si deseas iniciar un proyecto como experiencia educativa, el código pre-existente no es de ayuda o quizás el proyecto que deseas iniciar es muy especializado y sabes que no existe la posibilidad de que alguien más lo haya hecho ya. Pero generalmente, no hay necesidad en no investigar ya que las ganancias pueden ser grandiosas. Si los buscadores más utilizados no muestran nada, intenta tus búsquedas directamente en: github.com, ohloh.net, freecode.com, code.google.com, sourceforge.net, y en el directorio de software libre de la Free Software Foundation en directory.fsf.org.

Incluso si no se encuentra exactamente lo que estamos buscando, podría encontrar algo parecido, a lo que tiene más sentido unirse a ese proyecto y añadir funcionalidad en lugar de empezar desde cero por si mismo.

Empezando Con lo Que se Tiene

Has investigado, sin encontrar nada que realmente se adapte a tus necesidades, y decides iniciar un nuevo proyecto.

¿Ahora qué?

Lo más difícil acerca de lanzar un proyecto de software libre es transformar una visión privada a una pública. Tú y tu organización quizás sepan exactamente lo que deseas pero expresar ese objetivo de una manera comprensiva al resto del mundo tiene su trabajo. De hecho, es esencial, que te tomes tu tiempo para hacerlo. Tú y los otros fundadores deben decidir sobre qué va realmente el proyecto—eso es, decidir sus limitaciones, lo que no podrá hacer como lo que sí—y escribir una declaración de objetivos. Ésta parte no suele ser usualmente difícil, aunque puede revelar afirmaciones y desacuerdos sobre la naturaleza del proyecto, lo cual esta bien: mejor resolver esto ahora que luego. El próximo paso es empaquetar el proyecto para el consumo público, y esto es, básicamente, trabajo puro y duro.

Lo que lo hace laborioso es porque consiste principalmente en organizar y documentar lo que ya todo el mundo sabe—todos aquellos involucrados en el proyecto hasta ahora. Así que, para las personas trabajando ya, no existen beneficios inmediatos. Estos no necesitan de un fichero README que resuma el proyecto ni de un documento de diseño o manual de usuario. No necesitan de un árbol de código cuidadosamente ordenado conforme a los estándares informales, ampliamente utilizados para las distribuciones de fuentes. De cualquier forma como esté ordenado el código fuente estará bien, porque ya estarán acostumbrados de todas formas, y si el código funciona, saben cómo usarlo. Ni siquiera importa si las afirmaciones fundamentales sobre la arquitectura del proyecto siguen sin documentar, ya están familiarizados con lo que deben hacer.

En cambio, los recién llegados, necesitan de todas estas cosas. Afortunadamente, no las necesitan todas a la vez. No es necesario proporcionar todos los recursos posibles antes de tomar un proyecto público. Quizás en un mundo perfecto, todo nuevo proyecto open source empezaría su vida con un riguroso documento de diseño, un manual de usuario completo (marcando especialmente las características planeadas pero que aun no han sido implementadas), código empaquetado hermosamente y portable, capaz de ejecutar en cualquier plataforma y así sucesivamente. En realidad, cuidar de todos estos detalles consumiría demasiado tiempo, y de todas maneras, es trabajo con el que podrían ayudar otros una vez que el proyecto esté en marcha.

Por otro lado, lo que es necesario, es que se realice una inversión apropiada en la presentación, de forma que los recién llegados puedan superar el obstáculo inicial de no estar familiarizados con el proyecto. Pensemos en ello como en el primer paso en un proceso de inicio (bootstrapping), llevar al proyecto a un tipo de activación de energía mínima. He escuchado llamar a este umbral como hacktivation energy: la cantidad de energía que debe aportar un recién llegado antes de recibir algo a cambio. Mientras menor sea ésta energía, mejor. La primera tarea es hacer descender ésta hacktivation energy a niveles que animen a la gente a involucrarse.

Cada una de las siguientes secciones, describen un aspecto importante de iniciar un nuevo proyecto. Están presentadas casi en el mismo orden en el que un nuevo visitante las encontraría, aunque claro, el orden en el cual sean implementadas puede ser diferente. Incluso pueden ser tratadas como una lista de tareas. Cuando se inicie un proyecto, asegúrese de revisar la lista y de que cada uno de los elementos sean cubiertos, o al menos asegurar cierta comodidad con las posibles consecuencias de dejar alguna aparte.

Escoger un Buen Nombre

Colócate en la posición de alguien que acaba de escuchar acerca de su proyecto, quizás por alguien quien fortuitamente tropezó con éste mientras buscaba por alguna aplicación para resolver un problema. Lo primero que encontraran será el nombre del proyecto.

Un nombre genial no hará que automáticamente el proyecto tenga éxito, y un nombre malo no significa que éste acabado—bueno, en realidad un mal nombre probablemente podría hacer eso, pero empecemos asumiendo que nadie está activamente intentando hacer que su proyecto falle. De todos modos, un mal nombre puede desacelerar la adopción del programa porque la gente no se lo tome seriamente o porque simplemente les cueste recordarlos.

Un buen nombre:

  • Da cierta idea de lo que el proyecto hace, o al menos está relacionado de una manera obvia, como si alguien conoce el nombre y sabe lo que hace, después lo recordaran rápidamente.

  • Es fácil de recordar. Veamos, no hay nada de falso en el hecho de que el ingles se a convertido en el lenguaje por defecto de Internet: "fácil de recordar" significa "fácil de recordar para alguien que sepa leer en ingles." Los nombres que son juegos de palabras dependientes de la pronunciación en ingles nativo, por ejemplo, serán opacos para muchos lectores no nativos en ingles. Si el juego de palabras es particularmente llamativo y memorable, quizás sí valga la pena. Sólo recuerde que muchas personas al ver el nombre no lo escucharán en sus mentes de la misma manera que un ingles nativo lo haría.

  • No tiene el mismo nombre que otro proyecto y no infringe ninguna marca comercial. Esto es por buenos modales, y tener un buen sentido legal. No desea crear confusiones de identidad. Ya es bastante difícil mantenerse al día con todo lo que hay disponible en la red, sin tener diferentes cosas con el mismo nombre.

    Los enlaces mencionados anteriormente en “Primero Investiga” son muy útiles en descubrir si algún otro proyecto ya tiene el mismo nombre en el que estábamos pensando. Para los Estados Unidos, podemos encontrar buscadores gratuitos de marcas registradas en uspto.gov.

  • Está disponible como un nombre de dominio .com, .net, y .org. Hay que escoger alguno, probablemente .org, para promocionarse como el sitio oficial para el proyecto. Los otros dos deben reenviar allí simplemente para evitar que terceras partes creen una confusión de identidad sobre el nombre del proyecto. Incluso si piensa en hospedar el proyecto en otro sitio (vea “Hosting”) puede registrar los dominios específicos del proyecto y direccionarlos al sitio del hospedaje. Ayuda mucho a los usuarios tener que recordar sólo un URL.

  • Si es posible, está disponible como un nombre de usuario en Twitter y otros sitios de microblog. Ver “Poseer el nombre en los espacios de nombre importantes” para más información sobre esta y su relación con el nombre de dominio.

Poseer el nombre en los espacios de nombre importantes

Para los proyectos grandes, es una buena idea de poseer el nombre del proyecto en tantos espacios de nombre relevantes en Internet como puedas. Por espacios de nombres, me refiero no sólo al sistema de nombres de dominio, sino también a los servicios en línea en el que los nombres de la cuenta (nombres de usuario) son los manejadores visibles públicamente por el cual la gente se refiere al proyecto. Si tienes el mismo nombre en todos los lugares donde la gente te buscaría, haces fácil para las personas a mantener un leve interés en el proyecto hasta que estén listos para involucrarse más.

Por ejemplo, el proyecto de escritorio Gnome tiene el nombre de dominio gnome.org [12], el identificador de Twitter @gnome, el nombre de usuario gnome en Identi.ca[13], el nombre de usuario gnome en GitHub.com[14], y en la red freenode IRC (ver “IRC / Sistemas de Chat en Tiempo Real”) tienen el canal #gnome, aunque también mantienen sus propios servidores de IRC (donde, por supuesto, controlan el espacio de nombres de canal de todos modos).

Todo esto hace al proyecto Gnome espléndidamente fácil de encontrar: por lo general está justo donde un contribuyente potencial esperaría que estuviera. Por supuesto, Gnome es un proyecto grande y complejo con miles de colaboradores y muchas subdivisiones; la ventaja para Gnome de sea fácil de encontrar es mayor de lo que sería para un proyecto nuevo, ya que por ahora hay muchas maneras de participar en Gnome. Pero, sin duda, nunca dañará tu proyecto el poseer su nombre en la mayor cantidad de espacios de nombres relevantes como se pueda, y esto a veces puede ayudar. Así que cuando inicies un proyecto, piensa en cual debería ser su identificador en línea y registra ese identificador con los servicios de red que pienses que probablemente te interesan. Los mencionados anteriormente son probablemente una buena lista inicial, pero tu podrías conocer de otros que sean relevantes para el tema particular de tu proyecto.

Tener los objetivos claros

Una vez que se ha encontrado el sitio del proyecto, lo siguiente que la gente hace es buscar una descripción rápida o una declaración de objetivos, para poder decidir (en menos de 30 segundos) si están o no interesados en aprender más. Esto debe estar en un lugar prioritario en la página principal, preferiblemente justo debajo del nombre del proyecto.

La descripción de los objetivos debe ser concreta, limitada y sobre todo, corta. Aquí tenemos un buen ejemplo, de hadoop.apache.org:

El proyecto Hadoop® de Apache™ desarrolla software de código abierto para una computación distribuida confiable y escalable.

La biblioteca de software Apache Hadoop es un framework que permite el procesamiento distribuido de grandes conjuntos de datos a través de grupos de ordenadores que utilizan modelos de programación simples. Está diseñado para escalar de servidores individuales a miles de máquinas, cada uno ofreciendo computación y almacenamiento local. En lugar de confiar en el hardware para ofrecer alta disponibilidad, la biblioteca en sí está diseñado para detectar y controlar los errores en la capa de aplicación, de esa manera entregar un servicio de alta disponibilidad en la parte superior de un grupo de computadoras, cada una de las cuales puede ser propensa a fallas.

En pocas palabras, han logrado la máxima puntuación, en gran parte recurriendo a los conocimientos previos del lector. Ese es un punto importante: que está bien asumir un lector mínimamente informado con un nivel básico de preparación. Un lector que no sabe lo que significa "grupos de computadora" y "alta disponibilidad" en este contexto probablemente no puede hacer mucho uso de Hadoop de todos modos, así que no hay razon de escribir para un lector que sabe menos que eso. La frase "diseñado para detectar y controlar los errores en la capa de aplicación" destacará ante los ingenieros que tienen experiencia con la informática a gran escala de grupos—cuando vean esas palabras, sabrán que la gente detrás de Hadoop entiende ese mundo, y en consecuencia, estarán más dispuestos a tomar en cuanta a Hadoop.

Declara Que el Proyecto es Libre

La página principal debe poner claramente y sin ambigüedades que el proyecto es open source. Esto puede parecer obvio, pero es sorprendente cuantos proyectos se olvidan de esto. He visto sitios de proyectos de software libre donde la página principal no sólo no decía bajo cual licencia libre se distribuía la aplicación sino que ni siquiera declaraban que el software fuese libre. A veces, estas piezas cruciales de información eran relegadas a la página de descargas o a la página de los desarrolladores o a algún otro lugar el cual requería más de un enlace para llegar. En casos extremos, la licencia no se mostraba en ninguna parte del sitio—la única forma de encontrarla era descargando la aplicación y buscar adentr un archivo de licencia.

No cometáis estos errores. Una omisión como ésta puede haceros perder muchos desarrolladores y usuarios potenciales. Declarad desde el principio, justo debajo de la declaración de objetivos, que el proyecto es "software libre" u "open source", y mostrad la licencia exacta. Una guía rápida para escoger una licencia se encuentra en “Escogiendo una licencia y Aplicándola” más adelante en éste capítulo, y algunos detalles sobre las licencias serán discutidos en el Capítulo 9, Licencias, Copyrights y Patentes.

Llegados a este punto, nuestro visitante hipotético ha determinado— probablemente en un minuto o menos—que está interesado en utilizar, digamos, al menos cinco minutos más investigando el proyecto. La próxima parte describe qué debería encontrar durante esos cinco minutos.

Lista de Características y Requerimientos

Debería haber una breve lista de las características que el software soporta (si algo aun no ha sido completado, se puede listar de todas formas, pero señalando "planeado" o "en progreso") y el tipo de entorno necesario para ejecutar la aplicación. Hay que pensar en ésta lista como algo que daríamos a alguien que requiere un resumen de nuestro programa. Por ejemplo, la declaración de objetivos podría decir:

Crear un controlador y sistema de búsqueda con una API, para ser utilizada por programadores suministrando servicios de búsqueda para grandes colecciones de ficheros de texto.

La lista de características y requerimientos daría detalles que permitirían esclarecer el alcance de la declaración de objetivos:

Características

  • Búsquedas en texto plano, HTML y XML

  • Búsqueda de palabras o frases

  • (planeado) Emparejando borroso (Fuzzy Matching)

  • (planeado) Actualización incremental de índices

  • (planeado) Indexado de sitios web remotos

Requerimientos:

  • Python 2.2 o mayor

  • Espacio en disco suficiente para contener los índices (aproximadamente 2x el tamaño original de los datos)

Con ésta información, los lectores podrán rápidamente tener una idea de si éste programa tiene alguna esperanza de trabajar para ellos, y también pueden considerar involucrarse como desarrolladores.

Estado del Desarrollo

La gente siempre quiere saber cómo va un proyecto. Para proyectos nuevos, desean saber la separación entre las promesas del proyecto y la realidad del momento. Para proyectos maduros, desean saber cuan activamente es mantenido, cuan seguido sacan nuevas versiones, la facilidad para reportar fallos, etc.

Hay un par vías de diferentes para dar respuestas a estas preguntas, se debe suministrar una página que muestre el estado del desarrollo, listando los objetivos a corto plazo del proyecto y las necesidades (por ejemplo, quizás se estén buscando desarrolladores con un expertos en un tema en particular). Ésta página también puede dar una historia de versiones anteriores, con listas de las características, de manera que los visitantes obtengan una idea de cómo el proyecto define su "progreso" y de cuan rápidamente se hacen progresos de acuerdo a esa definición. Algunos proyectos estructuran su página de estado de desarrollo como una hoja de ruta que incluye el futuro: los acontecimientos pasados ​​se muestran en las fechas en que realmente sucedieron, los futuros sobre las fechas aproximadas en que el proyecto espera que vayan a pasar.

La otra manera — no mutuamente exclusiva con la primera, y de hecho, probablemente mejor realizarla en combinación con ella — es tener varios contadores e indicadores mantenidos de forma automática incrustados en la portada y/o la página destinada a desarrolladores del proyecto, que muestre varias piezas de información que, en conjunto, den una sensación del estado de desarrollo del proyecto y el progreso. Por ejemplo, un anuncio o grupo de noticias que muestran las noticias recientes, una cuenta de Twitter o de otro microblog mostrando avisos que coincidan con hashtags designados para el proyecto, una línea de tiempo de los últimos lanzamientos, un panel que muestra la actividad reciente en el gestor de fallos (fallos registrados, fallos respondidos), otro que muestre la actividad de la lista de correo o foro de discusión, etc. Cada uno de estos indicadores debería ser una puerta de entrada a más información de este tipo: por ejemplo, al hacer clic en el panel "fallos recientes" debe llevar al gestor de fallos completo, o por lo menos a una vista panorámica a la actividad de seguimiento de errores.

En realidad, hay dos significados ligeramente diferentes de "estado del desarrollo" que se confunden aquí. Uno de ellos es el sentido formal: ¿dónde se sitúa el proyecto en relación con sus objetivos declarados, y qué tan rápido está progresando. El otro es menos formal pero igual de útil: qué tan activo es este proyecto? ¿Hay personas aquí, están haciendo cosas?, A menudo, esta última noción es en lo que un visitante está más interesado. Ya sea que un proyecto cumplia su último hito o no a veces no es tan interesante como la cuestión más fundamental de si tiene una comunidad activa de desarrolladores alrededor.

Las dos nociones de estado de desarrollo están, por supuesto, relacionadas, y un proyecto bien presentado muestra los dos tipos. La información se puede dividir entre la portada del proyecto (mostrar suficiente allí para dar una visión general de los dos tipos de estado de desarrollo) y una página más orientado al desarrollador.

El estado del desarrollo debe reflejar siempre la realidad.

No hay que asustarse por parecer no estar preparado y nunca caer en la tentación de inflar el estado del desarrollo. Todos saben que el software evoluciona por etapas; no hay que avergonzarse en decir "Esto es software alfa con fallos conocidos. Ejecuta, y funciona algunas veces, así que uselo bajo su responsabilidad." Este lenguaje no asustará el tipo de desarrolladores que son necesarios en esta etapa. En cuanto a los usuarios, una de las peores cosas que un proyecto puede hacer es atraer usuarios antes de que el software éste listo para estos. Una reputación por inestabilidad y fallos es muy difícil de hacer desaparecer una vez adquirida. La paciencia da sus frutos a largo plazo; siempre es mejor que el software sea más estable de lo que espera el usuario ya que las sorpresas gratas producen el mejor boca a boca.

Descargas

EL software debe poder ser descargable como código fuente en formatos estándares, paquetes binarios (ejecutables) no son necesarios, a menos que el programa tenga requerimientos muy complicados para su compilado o dependencias que hagan hacerlo funcionar sea muy laborioso para la mayoría de las personas. (¡Aunque si es éste es el caso, el proyecto va a tenerlo muy difícil atrayendo programadores de todas maneras!)

El mecanismo de distribución debe de ser de lo más conveniente, estándar y sencillo posible. Si se estuviese intentando erradicar una enfermedad, no distribuiría la medicina tal que requiriese de una jeringuilla especial para administrarse. De igual manera, un programa debe ser conforme a métodos de compilación e instalación estándar; entre más se desvíe de estos estándares, mayor será la cantidad de usuarios y desarrolladores potenciales que se den por vencidos y abandonen el proyecto confundidos.

Esto parece obvio, pero muchos proyectos no se molestan en estandarizar sus procedimientos de instalación hasta mucho después, diciéndose a si mismos que esto lo pueden hacer en cualquier momento: "Ya resolveremos todas esas cosas cuando el código éste casi listo." De lo que no se dan cuenta es de que al dejar de lado el trabajo aburrido de terminar los procedimientos de compilado e instalación, en realidad están ralentizando todo—porque desalientan a los programadores que de otra manera habrían contribuido al código, si tan sólo pudieran construir y probarlo. Más dañino aun, no saben que están perdiendo a todos esos desarrolladores, porque el proceso es una acumulación de eventos que no suceden: alguien visita un sitios web, descarga el programa, intenta compilarlo, falla, deja de intentarlo y abandona. ¿Quién sabrá que ocurrió exceptuando a ésta persona? Nadie en el proyecto se dará cuenta que el interés y la buena voluntad de alguien a sido silenciosamente malgastada.

Las tareas aburridas con un alto beneficio siempre deben ser hechos al principio y disminuyendo de manera significativa las barreras de entrada a un proyecto utilizando buenos paquetes brindan altos beneficios.

Cuando se lanza un paquete descargable, dale un número de versión único, de manera que la gente pueda comparar dos versiones cualquiera diferentes y saber cual reemplaza a cual. De esa manera pueden informar de los errores en contra de un lanzamiento en particular (que ayuda a los que responden a averiguar si el error ya está solucionado o no). Una discusión detallada sobre la numeración de versiones puede ser encontrada en “Release Numbering”, y detalles sobre la estandarización de los procedimientos de compilado e instalación serán cubiertos en “Packaging”, ambos en el Capítulo 7, Packaging, Releasing, and Daily Development.

Control de versiones y Acceso al Bug Tracker

Descargar paquetes con el código fuente está bien para aquellos que sólo desean instalar y utilizar un programa, pero no es suficiente para aquellos que desean buscar fallos o añadir nuevas mejoras. Instantáneas nocturnas del código fuente pueden ayudar, pero esto no es suficiente para una prospera comunidad de desarrollo. Estas personas necesitan de acceso en tiempo real a los últimos cambios, y una manera de enviar cambios basados en esas fuentes.

La solución es utilizar un sistema de control de versiones — en concreto, una repositorio controlado por versiones, en línea, de acceso público, del que cualquiera puede echar un vistazo al proyecto y, posteriormente, obtener actualizaciones. Un repositorio de control de versiones es una señal  — para usuarios y desarrolladores — de que este proyecto está haciendo un esfuerzo para dar a la gente lo que necesitan para participar. Al escribir estas líneas, muchos proyectos de código abierto usan GitHub.com, que ofrece alojamiento ilimitado y gratuito de control de versiones públicas para proyectos de código abierto. Mientras GitHub no es la única opción, ni siquiera la única buena elección, es bastante razonable para la mayoría de los proyectos[15]. La infraestructura del control de versiones se discute detalladamente en “Control de Versiones” en Capítulo 3, Infraestructura Técnica.

Lo mismo ocurre con rastreador de errores del proyecto. La importancia de un sistema de seguimiento de fallos no sólo radica en su utilidad en el día a día para los desarrolladores, sino en lo que significa para los observadores del proyecto. Para muchas personas, una base de datos de errores accesible es uno de los signos más fuertes de que un proyecto se debe tomar en serio: cuanto mayor sea el número de errores en la base de datos, mejor se ve el proyecto. Esto puede parecer contrario a la intuición, pero recuerde que el número de informes de fallos archivados en realidad depende de tres cosas: el número absoluto de defectos de software reales presentes en el código, el número de personas que utilizan el software, y la comodidad con la que las personas pueden denunciar nuevos errores. De estos tres factores, los dos últimos son mucho más importante que el primero. Cualquier software de suficiente tamaño y complejidad tiene un número esencialmente arbitrario de fallos esperando a ser descubiertos. La verdadera pregunta es, ¿qué tan bien va a hacer el proyecto el registro y la priorización de esos fallos? Un proyecto con una base de datos de errores grandes y bien cuidada (que significa que los fallos sean atendidas sin demora, los errores duplicados están unificados, etc.), produce por lo tanto una mejor impresión que un proyecto con ninguna base de datos de errores, o de una base de datos casi vacía.

Claro está, que si un proyecto está empezando, que la base de datos de fallos contenga algunos pocos, y no hay mucho que se pueda hacer al respecto. Pero si la página de estado destaca la juventud del proyecto, y si la gente que busca en la base de datos de errores puede ver que la mayoría de los documentos presentados han tenido lugar recientemente, pueden extrapolar a partir de ahí que el proyecto sigue teniendo una tasa saludable de incidencias, y no van a alarmarse indebidamente por el bajo número absoluto de errores registrados.[16]

Hay que señalar que los bug trackers no sólo son usados para fallos en los programas sino también para peticiones de mejoras, cambios en la documentación, tareas pendientes y mucho más. Los detalles de ejecutar un sistema de seguimiento de fallos será cubierto en “Seguimiento de errores” en el Capítulo 3, Infraestructura Técnica, así que no vamos a entrar en detalles. Lo importante desde la perspectiva de la presentación está en tener un bug tracker y asegurarse de que es visible desde la página principal del proyecto.

Canales de Comunicación

Usualmente los visitantes desean saber cómo pueden contactar con los seres humanos detrás del proyecto. Hay que suministrar direcciones de listas de correo, salas de chat, canales en IRC (Capítulo 3, Infraestructura Técnica), y cualquier otro foro donde aquellos involucrados puedan ser contactados. Hay que dejar claro que los autores del proyecto están suscritos a estas listas, de manera que la gente vea una forma de dar feedback a los desarrolladores. La presencia de estos en las listas no implica obligación alguna de responder a todas las preguntas que se formulan o de implementar todas las peticiones. A la larga, probablemente solo una fraccción de los usuarios se unan a los foros de todas maneras, pero los demás estarán conformes con saber que podrían si fuese necesario.

En la primeras etapas de cualquier proyecto, no existe la necesidad de que haya una diferenciación entre los foros de los usuarios y los de los desarrolladores. Es mejor tener a todos los involucrados en el proyecto hablando en conjunto en una sala. Dentro de los primeros en adoptar el proyecto, la distinción entre usuario y desarrollador será muchas veces borrosa, hasta tal punto que la distinción no se puede hacer y la proporción entre programadores y usuarios usualmente es mayor al principio que al final. Mientras que no se puede asumir que todos quienes utilicen el programa sean programadores que quieren modificarlo, sí se puede asumir que al menos estan interesados en seguir las discusiones sobre el desarrollo y en obtener una visión de la dirección del proyecto.

Ya que éste capítulo es sólo sobre iniciar un proyecto, es suficiente decir que al menos estos foros de comunicación deben existir. Luego en “Manejando el crecimiento” en el Capítulo 6, Comunicaciones, examinaremos dónde y cómo montar estos foros, cómo deben ser moderados o cualquier otro tipo de dirección y cómo separar los foros de usuarios de los foros de los desarrolladores, cuando llegue el momento, sin crear un espacio infranqueable.

Pautas de Desarrollo

Si alguien considera contribuir al proyecto, buscará por pautas de desarrollo. Estas pautas son más sociales que técnicas: explican como los desarrolladores interactúan entre ellos y con los usuarios, y finalmente cómo hacer las cosas.

Este tema es tratado en detalle en “Tomando Nota de Todo” en Capítulo 4, Infraestructura Social y Política, pero los elementos básicos de unas pautas de desarrollo son:

  • enlaces a los foros para la interacción de los desarrolladores

  • instrucciones en cómo reportar fallos y enviar parches

  • alguna indicación de cómo el desarrollo es usualmente llevado a cabo y cómo se toman las decisiones—es el proyecto una dictadura benevolente, una democracia o algo más

Ningún sentido peyorativo es intencional por lo de "dictadura" por cierto. Es perfectamente aceptable ser un tirano donde un desarrollador en particular tiene el poder de veto sobre todos los cambios. Muchos proyectos exitosos funcionan de ésta manera. Lo importante es que el proyecto sea consciente de esto y lo comunique. Una tiranía pretendiendo ser una democracia desalentara a las personas; una tiranía que dice serlo funcionará bien siempre que el tirano sea competente y de confianza. (Ver “Forkability” en el Capítulo 4, Infraestructura Social y Política para conocer por qué la dictadura en proyectos de código abierto no tiene las mismas implicaciones que dictadura en otras áreas de la vida.)

subversion.apache.org/docs/community-guide es un ejemplo de pautas de desarrollo particularmente exhaustivas; las directrices de LibreOffice en wiki.documentfoundation.org/Development son también un buen ejemplo.

Proveer a los programadores una introducción a la aplicación es otro tema y será discutido en “Documentación para Desarrolladores” más adelante en éste capítulo .

Documentación

La documentación es esencial. Debe haber algo para que la gente lea, aunque sea algo rudimentario e incompleto. Esto entra de lleno en la categoría antes referida y usualmente es la primera área donde un proyecto falla. Conseguir una declaración de objetivos y una lista de requerimientos, escoger una licencia, resumir el estado de desarrollo—son todas tareas relativamente pequeñas que pueden ser completadas y a las que usualmente no es necesario volver una vez terminadas. La documentación, por otra parte, nunca está terminada realmente, lo cual puede que sea una de las razones por las cuales se retrase su inicio.

La cuestión más insidiosa sobre la utilidad de la documentación es que es inversamente proporcional para quienes la escriben y para quienes la leen. Lo más importante de la documentación para un usuario inicial es lo más básico: cómo configurar la aplicación, una introducción de cómo funciona y quizás algunas guías para realizar las tareas más comunes. Pero a la vez son estas cosas las más sabidas por aquellos quienes escriben la documentación— tan bien sabidas que puede ser difícil para estos ver las cosas desde el punto de vista de los lectores, dificultando listar los pasos que (para los escritores) parecen tan obvios que no merecen especial atención.

No existe una solución mágica para éste problema. Alguien debe sentarse y escribir todo esto, para luego, y lo más importante, incorporar los comentarios de los lectores nuevo tipo y probar la calidad. Hay que utilizar un formato simple y fácil de modificar como HTML, texto plano, Markdown, ReStructuredText, o alguna variante de XML—algo que sea conveniente para mejoras rápidas, ligeras e imprevisibles para el momento[17]. Esto no es sólo para eliminar cualquier trabajo innecesario a los escritores originales realizar cambios incrementales, sino que también para quienes se unan al proyecto después y desean trabajar en la documentación.

Una manera de asegurarse de que la documentación básica inicial se hace, es limitando su alcance. Al menos de ésta manera no parecerá que se está escribiendo una tarea sin fin. Una buena regla es seguir unos criterios mínimos:

  • Avisar al lector claramente el nivel técnico que se espera que tenga.

  • Describir clara y extensivamente cómo configurar el programa y en alguna parte al inicio de la documentación comunicarle al usuario cómo ejecutar algún tipo de prueba de diagnóstico o un simple comando para confirmar que todo funciona correctamente. La documentación inicial es a veces más importante que la documentación de uso. Mientras mayor sea el esfuerzo invertido en instalar y tener funcionando la aplicación, mayor será la persistencia en descubrir funcionalidades avanzadas o no documentadas. Cuando alguien abandona, abandonan al principio; por ello, las primeras etapas como la instalación, necesiten la mayor ayuda.

  • Dar un ejemplo estilo tutorial de como realizar alguna tarea común. Obviamente, muchos ejemplos para muchas tareas sería mejor, pero si el tiempo es limitado, es mejor escoger una tarea en específico y llevar al usuario de la mano paso por paso. Una vez que se ve que la aplicación puede ser utilizada , empezarán a explorar qué más es lo que puede hacer—y si se tiene suerte empezar a documentarlo ellos mismos. Lo que nos lleva al siguiente punto...

  • Indicar las áreas donde se sabe que la documentación es incompleta. Al mostrar a los lectores que se es consciente de las deficiencias, nos alineamos con su punto de vista. La empatía les da confianza en que no van a tener que luchar para convencer al proyecto de su importancia. Estas indicaciones no necesitan representar promesa alguna de completar los espacios en blanco en una fecha en particular—es igualmente legitimo tratarlas como requisitos abiertos para ayudantes voluntarios.

Ese último criterio es de una especial importancia, y puede ser aplicado al proyecto entero, no sólo a la documentación. Una gestión exacta de las deficiencias conocidas es la norma en el mundo Open Source. No se debe exagerar en las faltas del proyecto, solo identificarlas escrupulosa y desapasionadamente cuando sea necesario (sea en la documentación, en la base de datos de fallos o en discusiones en la lista de correos). Nadie verá esto como derrotismo por parte del proyecto, ni como una responsabilidad explícita. Ya que cualquiera que utilice la aplicación descubrirá sus deficiencias por si mismos, es mejor que estén psicológicamente preparados—entonces parece que el proyecto tiene un sólido conocimiento acerca de como va progresando.

Disponibilidad de la documentación

La documentación debe ser accesible desde dos sitios: en línea (directamente desde el sitio web), y en la distribución descargable de la aplicación (consultar “Packaging” en el Capítulo 7, Packaging, Releasing, and Daily Development). Debe estar en línea y navegable porque a menudo se lee la documentación antes de descargar el programa por primera vez, como una ayuda en la decisión de descargarlo o no. Pero también debe acompañar al programa, bajo la premisa de que la descarga debe suministrar todo lo necesario para utilizar el paquete.

Para la documentación en línea, hay que asegurarse de que hay un enlace que muestra toda la documentación en una página HTML (indicando algo como "monolito" o "todo-en-uno" o "sólo un gran fichero" al lado del enlace, de tal manera que se sepa que puede tardar un poco en cargar). Esto es muy útil porque a veces sólo desean buscar una sola palabra o frase en la documentación. Generalmente, las personas ya saben qué es lo que están buscando; sólo que no recuerdan en cual sección está. Para estas personas, nada es más frustrante que encontrar una página para la tabla de contenidos, luego otra diferente para la introducción, luego otra diferente para las instrucciones de instalación, etc. Cuando las páginas están divididas de esta manera, la función de búsqueda de sus navegadores es inútil. Este estilo de páginas separadas es útil para quienes ya saben cual es la sección que necesitan, o que desean leer toda la documentación de principio a fin en secuencia. Pero esta no es la forma más común en que la documentación es leída. Ocurre más a menudo que alguien que conoce algo básico de la aplicación vuelve para buscar una palabra o frase. Fallar al suministrarles un sólo documento en el que se puedan realizar búsquedas, es hacerles la vida más dura

Documentación para Desarrolladores

La documentación para los desarrolladores es escrita para ayudar a los programadores a entender el código y puedan arreglarlo o extenderlo. Esto es algo diferente a las pautas de desarrollo discutidas anteriormente, que son más sociales que técnicas. Estas pautas para los desarrolladores le dicen a los programadores como deben desenvolverse entre ellos. La documentación les dice como deben desenvolverse con el código en si mismo. Por conveniencia las dos vienen juntas en un sólo documento (como sucede con el ejemplo anterior subversion.apache.org/docs/community-guide) pero no es obligatorio.

A pesar de que la documentación para los desarrolladores puede ser de mucha ayuda, no existe ninguna razón para retrasar un lanzamiento por hacerla. Es suficiente para empezar que los autores originales estén disponibles (y dispuestos) a responder a preguntas sobre el código. De hecho, tener que responder la misma pregunta varias veces es una motivación muy común para escribir dicha documentación. Pero antes de que sea escrita, determinados contribuyentes serán capaces de desenvolverse con el código ya que la fuerza que hace que las persones utilicen su tiempo en leer el código base es que éste código les resulta útil. Si las personas tienen fé en ello, ninguna cantidad de documentación hará que vengan o los mantendrá.

Así que si hay tiempo para escribir documentación sólo para una audiencia, que sea para los usuarios. Toda la documentación para los usuarios es, en efecto, documentación para desarrolladores también. Cualquier programador que vaya a trabajar en un proyecto necesita estar familiarizado con su uso. Luego, cuando se vea a los programadores preguntando las mismas preguntas una y otra vez, habrá que tomarse el tiempo de escribir algunos documentos aparte sólo para estos.

Algunos proyectos utilizan wikis para su documentación inicial o incluso para su documentación principal. En mi experiencia, esto es efectivo si y sólo si, el wiki es editado activamente por algunas personas que se ponen de acuerdo en como la documentación debe ser organizada y la voz que debe tener. Más en “Wikis” en el Capítulo 3, Infraestructura Técnica.

Demos, Capturas de Pantalla, Videos y Ejemplos de Salidas

Si el proyecto incluye una interfaz gráfica de usuario, o si produce una salida gráfica o alguna salida peculiar, coloca algunas muestras en el sitio web del proyecto. En el caso de la interfaz, esto significa capturas o, mejor aún, un breve video (de 4 minutos o menos) con subtítulos o un narrador. Para la salida, podría ser capturas de pantalla o sólo archivos de ejemplo para descargar. Para el software basado en web, el patrón de oro es un sitio de demostración, por supuesto, asumiendo que el software se presta para eso.

Lo principal es atender el deseo de gratificación que tiene la gente de la manera más probable que ellos puedan esperar. Una sola pantalla o video pueden ser más convincente que párrafos de texto descriptivo y charlas en listas de correo, ya que es una prueba de que el software funciona. El código todavía puede tener errores, puede ser difícil de instalar, puede estar documentado de forma incompleta, pero la evidencia basada en la imagen muestra a la gente que si uno pone en el esfuerzo suficiente, se puede conseguir que se ejecute.

Existen muchas otras cosas que se pueden poner en el sitio web del proyecto, si se tiene el tiempo, o si por alguna razón u otra son especialmente apropiadas: página de noticias, historia, enlaces relacionados, función de búsqueda, enlace para donaciones, etc. Ninguno de estos es necesarios al principio, pero hay que tenerlos en mente para el futuro.

Hosting

¿Dónde en Internet hay que poner los materiales del proyecto?

Un sitio web, obviamente — pero la respuesta completa es un poco más complicada que esa.

Muchos proyectos distinguen entre su sitio web público primario de cara al usuario — el que tiene las fotos bonitas y la página "Acerca de..." y las presentaciones suaves y videos y visitas guiadas y todo eso — y sus sitio para desarrolladores, donde todo está sucio y lleno de texto estrechamente espaciado en fuentes de espacio sencillo y abreviaturas impenetrables.

Bueno, estoy exagerando. Un poco. En cualquier caso, en las primeras etapas de tu proyecto, no es tan importante distinguir entre estos dos tipos de público. La mayoría de los visitantes interesados que consigues son los desarrolladores, o por lo menos la gente que se sienten cómodos probando nuevo código. Con el tiempo, puede que tenga sentido tener un sitio de cara a los usuarios (por supuesto, si tu proyecto es una biblioteca de código, los "usuarios" podrían ser otros programadores) y un área de colaboración algo distinto para los interesados ​​en participar en el desarrollo. El sitio de colaboración tendría el repositorio de código, gestor de fallos, wiki desarrollo, enlaces a listas de correo de desarrollo, etc. Los dos sitios deben unirse entre sí, y, en particular, es importante que el sitio orientado al usuario deje en claro que el proyecto es código abierto y dónde se puede encontrar la actividad de desarrollo de ese código abierto[18]

En el pasado, muchos proyectos crearon su sitio de desarrolladores y la infraestructura por sí mismos. Durante la última década, sin embargo, la mayoría de los proyectos de código abierto — y casi todos los nuevos — sólo tienen que utilizar uno de los sitios de "alojamiento enlatado" que han surgido para ofrecer estos servicios de forma gratuita a proyectos de código abierto. Con mucho, el más popular de estos sitios, mientras escribo esto, a mediados de 2013, es GitHub.com, y si usted no tiene una fuerte preferencia sobre dónde alojar, probablemente debería simplemente elegir GitHub; muchos desarrolladores ya están familiarizados con él y tienen cuentas personales allí. “Hosting Enlatado” en Capítulo 3, Infraestructura Técnica tiene una discusión más detallada de las cuestiones a considerar al elegir un sitio de alojamiento enlatado, y un resumen de los más populares.



[12] Ellos no lograron obtener gnome.com o gnome.net, pero eso está bien — si sólo tienes uno, y es .org, está bien. Ese es por lo general el primero que la gente busca cuando está buscando un proyecto de código abierto con ese nombre. Si no podían conseguir "gnome.org" en sí, una solución típica sería la de obtener "gnomeproject.org" en su lugar, y muchos proyectos resuelven el problema de esa manera.

[13] Identi.ca es un microblog / red social que un número de desarrolladores de software libre usa; su código es de fuente abierta y está disponible en pump.io. Para los proyectos orientados a desarrolladores, recomiendo al menos hacer todas las micro actualizaciones de estado — coloquialmente conocidas como "tweets" — tanto en Identi.ca como en Twitter. Mientras que el número total de personas en Identi.ca es mucho menor que en Twitter, el porcentaje de ellos que son susceptibles de estar interesados ​​en las noticias acerca de un proyecto de código abierto es mucho más alto, por lo menos a partir de este escrito en el año 2013 y durante algunos años anteriores a este.

[14] Mientras que la copia maestra del código fuente de Gnome está en git.gnome.org, ellos mantienen un espejo en GitHub, ya que muchos desarrolladores ya están familiarizados con GitHub

[15] Aunque GitHub se basa en Git, un sistema de control de versiones de código abierto muy popular, el código que ejecuta los servicios web de GitHub no es en sí mismo fuente abierta. Si esto es importante para su proyecto es una cuestión compleja, y se aborda con mayor profundidad en “Hosting Enlatado” en Capítulo 3, Infraestructura Técnica

[16] Para una discusión más a fondo de que los informes de fallos deben ser tratados como una buena noticia, consulte en rants.org/2010/01/10/bugs-users-and-tech-debt, un artículo que escribí en 2010 sobre cómo los informes de error no no representan una "deuda técnica" sino más bien participación de los usuarios.

[17] No te preocupes demasiado por elegir el formato correcto la primera vez. Si cambias de opinión más tarde, siempre se puede hacer una conversión automatizada usando Pandoc.

[18] A partir de agosto de 2013, un buen ejemplo de un proyecto con los sitios primarios y de desarrolladores independientes pero bien vinculados es el Ozone Widget Framework: comparar su sitio principal orientado al usuario en ozoneplatform.org, con su área de desarrollo en github.com/ozoneplatform/spf.