Documentación

Debe incluir la declaración de propósito y el resto de informaciones que a lo largo de este documento se menciona que se tienen que incluir en el README.

Se tiene que redactar en inglés y el formato tiene que ser texto con algún lenguaje de marcas ligero. Puede no tener extensión si contiene solo texto plano o una extensión que indique con qué formato de marcas se tiene que interpretar (es decir, en realidad el fichero tendrá nombre README.md si está escrito en Markdown).

El contenido de este fichero (concretamente la versión que esté colgada en la rama master), formateado según las convenciones del lenguaje de marcas que se haya utilizado, es lo que GitHub muestra como portada de la web de desarrollo. Por lo tanto, conviene comprobar que el formato es correcto y que se visualiza bien en un navegador web.

Para la web orientada a usuarios del proyecto, es aceptable escribir directamente HTML. El resto de documentación, esté o no incluida en el repositorio de código, estará en el formato de wiki correspondiente, o bien en uno de los siguientes formatos:

Las entidades adjudicatarias de contratos —tanto de desarrollo como de despliegue— tienen que entender que no tendrán el monopolio de la configuración, el despliegue y el mantenimiento del producto.

Desde muy pronto tiene que haber una documentación accesible desde la web que explique cómo utilizar el producto a diferentes niveles o para diferentes roles: usuarios corrientes, administradores, etcétera. En el caso de librerías de código, los usuarios son programadores que no participan en el proyecto.

Tiene que valorarse adecuadamente en qué idiomas tiene que estar esta documentación, dependiendo de cuál sea el ámbito esperado de uso del producto. Se puede tener el catalán o el castellano como idioma principal de la documentación, pero, como mínimo, las tareas principales de administración deben explicarse también en inglés. Si llegan muestras de interés desde otros territorios, convendrá que toda la documentación de usuario se encuentre también traducida al inglés. En el caso de librerías de código o herramientas de desarrollo, toda la documentación tiene que estar desde el principio en inglés.

La documentación nunca será completa y estará en constante evolución. Por eso conviene que sea fácilmente actualizable por diferentes personas y recomendamos inicialmente usar una wiki. Utilizar la misma wiki de GitHub nos evita tener que preparar más infraestructura y facilita que la documentación se encuentre automáticamente enlazada desde la página web del repositorio.

Hasta que no haya mucha documentación de usuario/a, es recomendable mantenerla toda unida en una misma página de la wiki, con una tabla de contenidos al inicio, y no subdividirla en páginas, ya que así se facilita la búsqueda de palabras clave utilizando las funciones de búsqueda del navegador. Desde esta página conviene enlazar el resto de elementos de documentación, como las instrucciones de instalación, posibles tutoriales, o la posible lista de preguntas frecuentes (FAQ).

Enlazar desde:

El procedimiento de instalación desarrollado en la medida (Día 1) Implementar procedimientos de build e instalación con herramientas libres y de uso extendido tiene que estar explicado en un fichero INSTALL en la raíz del repositorio principal.

Se tiene que redactar en inglés y el formato tiene que ser texto con algún lenguaje de marcas ligero.

Conviene incluir alguna medida o comando de diagnóstico que permita al usuario saber si la instalación se ha ejecutado correctamente (por ejemplo, ejecutar un juego de pruebas, y especificar el resultado esperado).

El fichero de instalación debe estar enlazado como mínimo desde:

Por defecto, hay que utilizar la licencia Creative Commons Zero v1.0 Universal (CC0-1.0).

Un resumen de sus características se puede encontrar en: https://tldrlegal.com/license/creative-commons-cc0-1.0-universal .

En el caso de la documentación, no tiene por qué utilizarse la misma licencia que para el software en sí, y, de hecho, en este caso sí que son admisibles las licencias de dominio público.

En caso de crear documentación para proyectos externos, hay que utilizar las licencias que estos proyectos ya estén utilizando.

Por defecto, hay que utilizar la licencia Creative Commons Attribution Share Alike 4.0 (CC-BY-SA-4.0).

Seguir https://wiki.creativecommons.org/wiki/Website/Publish y https://creativecommons.org/choose/#metadata .

Para entender sus características se puede consultar: https://tldrlegal.com/license/creative-commons-attribution-sharealike-4.0-international-(cc-by-sa-4.0).[https://tldrlegal.com/license/creative-commons-attribution-sharealike-4.0-international-(cc-by-sa-4.0)].