Documentación
-
Día1
-
Plugin
-
NuevoProducto
-
Publicació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.
-
Integración
-
Plugin
-
NuevoProducto
-
Publicación
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:
-
Asciidoc
-
Markdown
-
ReStructuredText (es el que utiliza por defecto Sphinx)
-
Org Mode
-
Contratar
-
Integración
-
Adaptación
-
Plugin
-
NuevoProducto
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.
-
Integración
-
Plugin
-
NuevoProducto
-
Publicación
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:
-
La web del proyecto.
-
El fichero
README
del repositorio principal.
-
Plugin
-
NuevoProducto
Esta es una alternativa para proyectos que crecen mucho y que posiblemente hayan empezado poniendo la documentación en la wiki. Se tiene que traspasar toda la información que haya en la wiki al nuevo formato, y eliminar la wiki para no confundir a los usuarios. Si se tiene claro desde el principio que el proyecto requerirá una buena cantidad de documentación, se puede optar desde el principio por esta vía.
Toda la documentación irá a un subdirectorio doc dentro de la raíz del repositorio y se escribirá o bien en ReStructuredText o bien en Markdown, los dos lenguajes de marcas que soporta Sphinx.
En este caso, por tratarse de proyectos grandes y que tienen que aspirar a llegar a públicos amplios, la documentación tendrá que estar necesariamente en inglés, sin perjuicio de que se pueda traducir a otros idiomas.
Tener el código y la documentación en un mismo repositorio, lejos de ser un problema, facilita que ambos vayan sincronizados y que eso quede reflejado en el historial de commits.
Enlazar desde:
-
La web del proyecto.
-
El fichero
README
del repositorio principal.
Un ejemplo lo podemos encontrar en: https://github.com/commercialhaskell/stack/tree/master/doc.
- Recomendación: Crear y mantener un listado de FAQ R_4B1
-
Tags: NuevoProducto Publicación + Links incoming: None + Links outgoing: None + Si se realiza de forma reactiva pero diligente, con preguntas reales de los usuarios, puede facilitar en gran medida que se encuentre rápidamente la información que se necesita y puede resultar una manera muy rentable de invertir los recursos del proyecto.
-
Plugin
-
NuevoProducto
-
Publicación
-
Día1
-
Integración
-
Plugin
-
NuevoProducto
-
Publicación
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:
-
El fichero
README
del repositorio principal.
-
NuevoProducto
Para proyectos web grandes que quieran atraer la atención de muchas personas, el mejor reclamo es un demo site.
Un vídeo explicando el uso y las características de la herramienta también puede resultar muy atractivo.
Si el producto tiene una interfaz de usuario gráfica, es muy recomendable acompañar las explicaciones con capturas de pantalla. También se pueden utilizar en el listado de funcionalidades descrito en la #h:2dc43f4e-e755-4fe5-be4e-1f9dd58fe9e9[medida Especificar en sitios fácilmente accesibles un listado de funcionalidades].
-
Integración
-
Plugin
-
NuevoProducto
-
Publicación
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.
-
Documento
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)].