La creació de programari i la realització dels seus projectes porta associada la creació i gestió de la documentació associada. Cada pas en la creació i producció de programari genera documentació que s’ha de preveure i gestionar. La gestió correcta d’aquesta documentació permet controlar els projectes, en facilita la utilització per part de l’usuari i en disminueix els costos. El concepte de documentació de programari comprèn diferents tipus de documentació i implica diferents rols:
– Documentació d’arquitectura/disseny: defineix les pràctiques, tècniques i tipus de representacions utilitzades pels arquitectes de programari per enregistrar una arquitectura de programari. Una de les branques de la fase de disseny de programari implica la creació d’un llibre blanc sobre aspectes concrets del sistema com la interfície de disseny o el codi. El document de disseny i els elements de disseny són útils per als dissenyadors, desenvolupadors, administradors, etc. de les bases de dades o aplicacions.
–Documentació tècnica: acompanya al programari i descriu diversos aspectes del seu funcionament. Documenta el codi, els algoritmes, les interfícies i APIs. La documentació tècnica pot ser utilitzada pels desenvolupadors, provadors i també pels clients finals. Diverses eines com Doxygen, Ndoc, RoboDoc, etc. permeten generar automàticament documentació a partir del codi font i crear manuals de referència en formes com ara arxius de text o HTML .
Captura de pantalla del projecte del sistema operatiu Chromium
– Requisits de software: els requisits són la descripció del que un programari farà o no farà i són declaracions que identifiquen atributs, capacitats, característiques o qualitats d’un sistema. Els requisits afecten tots els agents involucrats en la producció: usuaris, clients, gerents, vendes, màrqueting, arquitectes de programari, enginyers d’usabilitat, dissenyadors d’interacció, desenvolupadors, etc. Es mostren en varietat d’estils i notacions i poden ser especificats com a declaracions de llenguatge natural, fórmules matemàtiques, dibuixos o totes aquestes combinades. La necessitat de documentació dels requisits està relacionada amb la complexitat del producte i el seu impacte.
– Documentació per a l’usuari final: són els manuals per a l’usuari final, administradors de sistemes i personal de suport i expliquen com funciona el programa. El manual descriu cada funció del programa i ajuda l’usuari, i també pot proporcionar assistència per solucionar problemes més a fons. És molt important que els documents d’usuari estiguin al dia. Tot i que no necessiten estar organitzats d’una manera determinada, és important que tinguin un índex exhaustiu. La documentació de l’usuari es considera que constitueix un contracte que especifica què farà el programari. Les tres formes bàsiques de la documentació d’usuari són el tutorial, l’enfocament temàtic i la llista de referència.
– Documentació de màrqueting: per a determinades tipologies de programari és necessari disposar de diferents materials promocionals. La documentació informa què fa el producte exactament i impel·leix el possible comprador a comprar-lo.
Programari lliure
En relació amb la documentació de programari lliure es considera que sovint els manuals i la documentació disponible és incompleta o de baixa qualitat. És a dir, de vegades el problema no és el programari lliure en si, sinó la documentació que l’acompanya. Sense una documentació completa i fiable, el procés de creació de programari és incomplet. Com a solució es proposa la utilització d’una llicència de programari lliure com la del sistema operatiu GNU: https://www.gnu.org/licenses/fdl-1.3.en.html. GNU també ofereix a la seva plana web una llista de llicències lliures per a documentació de programari: https://www.gnu.org/philosophy/license-list.html#FreeDocumentationLicenses.
Recursos sobre documentació de programari
– Enllaços:
Beautiful docs: Llista col·laborativa de recursos per a la creació de documentació de programari que s’actualitza regularment. Conté enllaços per escriure documentació i eines per generar documentació.
Software Documentation.info: Plana web extensa dedicada a la documentació de programari. Ofereix eines i recursos per a la documentació.
Categoria de documentació de programari a Viquipèdia: Inclou recursos i enllaços a programes, eines, projectes i articles sobre la documentació.
Yevgeniy Brikman. Youarewhatyou document. http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html. [Data de consulta: 1 de juny del 2014]: Ampli article que recull multitud d’enllaços i casos pràctics ordenats segons categories i temes. És un article interessant per iniciar-se en el tema.
A begginers guide to write documentation: Lloc web amb informació, recursos, fòrum de documentalistes que serveix com a punt de trobada de documentalistes de programari. Periòdicament organitzen trobades professionals i conferències.
Perfils de Twitter que parlen sobre documentació:
Bibliografia:
McConnell’s, Steve. Code complete. A PracticalHandbook of Software Construction. 2a ed. EUA: Microsoft books, 2004. 960 p.ISBN-10: 0735619670.
Yevgeniy Brikman. You are what you document. http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html. [Accés: 1 de juny del 2014]: Ampli article que recull multitud d’enllaços i casos pràctics ordenats segons categories i temes. Software documentation.
http://en.wikipedia.org/wiki/Software_documentation. [Data de consulta: 30 de maig del 2014]. Why Free Software needs Free Documentation. https://www.gnu.org/philosophy/free-doc.en.html. [Data de consulta: 1 de juny del 2014]. Documentació de programes en programari lliure.
http://www.eoi.es/wiki/index.php/Documentaci%C3%B3n_de_programas_en_Software_libre. [Data de consulta: 31 de maig del 2014]
Deixa un comentari