Documentació

Ha d’incloure la declaració de propòsit i la resta d’informacions que al llarg d’aquest document es menciona que s’han d’incloure en el README.

S’ha de redactar en anglès i el format ha de ser text amb algun llenguatge de marques lleuger. Pot no tenir extensió si conté només text pla o una extensió que indiqui amb quin format de marques s’ha d’interpretar (és a dir, en realitat es el fitxer tindrà nom README.md si està escrit en Markdown).

El contingut d’aquest fitxer (concretament la versió que hi hagi penjada a la branca master), formatat segons les convencions del llenguatge de marques que s’hagi utilitzat, és el que GitHub mostra com a portada de la web de desenvolupament. Per tant, convé comprovar que el format és correcte i que es visualitza bé en un navegador web.

Per la web orientada a usuaris del projecte és acceptable escriure directament HTML. La resta de documentació, estigui o no inclosa en el repositori de codi, estarà en el format de wiki corresponent, o bé en un dels següents formats:

Les entitats adjudicatàries de contractes — tant de desenvolupament com de desplegament — han d’entendre que no tindran el monopoli de la configuració, el desplegament i el manteniment del producte.

Des de ben aviat hi ha d’haver una documentació accessible via web que expliqui com utilitzar el producte a diferents nivells o per a diferents rols: usuaris corrents, administradors, etcètera. En el cas de llibreries de codi els usuaris son programadors que no participen en el projecte.

S’ha de valorar bé en quins idiomes ha d’estar aquesta documentació, depenent de quin sigui l’àmbit esperat d’ús del producte. Es pot tenir el català o el castellà com a llengua principal de la documentació, però com a mínim les tasques principals d’administració cal també explicar-les en anglès. Si arriben mostres d’interès des d’altres territoris, convindrà que tota la documentació d’usuari es trobi també traduïda a l’anglès. En el cas de llibreries de codi o eines de desenvolupament, tota la documentació ha d’estar des de l’inici en anglès.

La documentació mai serà complerta i estarà en constant evolució. Per això convé que sigui fàcilment actualitzable per diferents persones i recomanem inicialment usar una wiki. Fer servir la mateixa wiki de GitHub ens evita haver de preparar més infraestructura i fa que la documentació es trobi automàticament enllaçada des de la pàgina web del repositori.

Fins que no hi hagi molta documentació d’usuari/-a, és recomanable mantenir-la tota junta en una mateixa pàgina de la wiki, amb una taula de continguts a l’inici, i no subdividir-la en pàgines, ja que així es facilita la cerca de paraules clau utilitzant les funcions de cerca del navegador. Des d’aquesta pàgina convé enllaçar la resta d’elements de documentació com les instruccions d’instal·lació, possibles tutorials, o la possible llista de FAQ.

Enllaçar des de:

El procediment d’instal·lació desenvolupat a la Mesura: (Dia 1) Implementar procediments de build i instal·lació amb eines lliures i d’ús estès ha d’estar explicat en un fitxer INSTALL a l’arrel del repositori principal.

S’ha de redactar en anglès i el format ha de ser text amb algun llenguatge de marques lleuger.

Convé incloure alguna mesura o comanda de diagnòstic que permeti a l’usuari saber si la instal·lació s’ha executat correctament (per exemple, executar un joc de proves, i especificar el resultat esperat).

El fitxer d’instal·lació ha d’estar enllaçat com a mínim des de:

Per defecte utilitzar la llicència Creative Commons Zero v1.0 Universal (CC0-1.0).

Un resum de les seves característiques es pot trobar a: https://tldrlegal.com/license/creative-commons-cc0-1.0-universal.

En el cas de la documentació no té per què fer-se servir la mateixa llicència que per al programari en sí, i de fet en aquest cas sí que son admissibles les llicències de Domini Públic).

En cas de crear documentació per projectes externs, utilitzar les llicències que aquests projectes ja estiguin fent servir.

Per defecte utilitzar la llicència Creative Commons Attribution Share Alike 4.0 (CC-BY-SA-4.0).

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

Per entendre les seves característiques es pot 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)].