Documentació del programari

La documentació de programari és text escrit o il·lustració que acompanya el programari informàtic o està incrustat al codi font. La documentació explica com funciona el programari o com utilitzar-lo, i pot significar coses diferents per a persones amb rols diferents.

La documentació és una part important de l'enginyeria de programari. Els tipus de documentació inclouen:

• Requisits: afirmacions que identifiquen els atributs, les capacitats, les característiques o les qualitats d'un sistema. Aquesta és la base del que s'implementarà o s'ha implementat.
• Arquitectura/Disseny: Visió general del programari. Inclou les relacions amb un entorn i els principis de construcció que s'utilitzaran en el disseny de components de programari.
• Tècnica: documentació de codi, algoritmes, interfícies i API.
• Usuari final: manuals per a l'usuari final, els administradors del sistema i el personal de suport.
• Màrqueting: com comercialitzar el producte i anàlisi de la demanda del mercat.

Tipus

Documentació de requisits

La documentació de requisits és la descripció del que fa o hauria de fer un programari en particular. S'utilitza durant tot el desenvolupament per comunicar com funciona el programari o com es pretén que funcioni. També s'utilitza com a acord o com a base per a l'acord sobre el que farà el programari. Els requisits són produïts i consumits per tots els implicats en la producció de programari, incloent-hi: usuaris finals, clients, gestors de projectes, vendes, màrqueting, arquitectes de programari, enginyers d'usabilitat, dissenyadors d'interacció, desenvolupadors i provadors.

Els requisits vénen en una varietat d'estils, notacions i formalitats. Els requisits poden ser similars a un objectiu (per exemple, un entorn de treball distribuït ), propers al disseny (per exemple, les compilacions es poden iniciar fent clic amb el botó dret en un fitxer de configuració i seleccionant la funció "build" ) i qualsevol cosa entremig. Es poden especificar com a declaracions en llenguatge natural, com a figures dibuixades, com a fórmules matemàtiques detallades o com una combinació de totes elles.

La variació i la complexitat de la documentació de requisits la converteixen en un repte demostrat. Els requisits poden ser implícits i difícils de descobrir. És difícil saber exactament quanta i quin tipus de documentació es necessita i quanta es pot deixar per a la documentació d'arquitectura i disseny, i és difícil saber com documentar els requisits tenint en compte la varietat de persones que llegiran i utilitzaran la documentació. Per tant, la documentació de requisits sovint és incompleta (o inexistent). Sense una documentació de requisits adequada, els canvis de programari es tornen més difícils i, per tant, més propensos a errors (disminució de la qualitat del programari) i requereixen més temps (són cars).

La necessitat de documentació de requisits sol estar relacionada amb la complexitat del producte, l'impacte del producte i l'esperança de vida del programari. Si el programari és molt complex o ha estat desenvolupat per molta gent (per exemple, programari per a telèfons mòbils), els requisits poden ajudar a comunicar millor què s'ha d'aconseguir. Si el programari és crític per a la seguretat i pot tenir un impacte negatiu en la vida humana (per exemple, sistemes d'energia nuclear, equips mèdics, equips mecànics), sovint es requereix una documentació de requisits més formal. Si s'espera que el programari només duri un mes o dos (per exemple, aplicacions per a telèfons mòbils molt petites desenvolupades específicament per a una determinada campanya), pot ser que es necessiti molt poca documentació de requisits. Si el programari és una primera versió sobre la qual es basa posteriorment, la documentació de requisits és molt útil a l'hora de gestionar el canvi del programari i verificar que no s'hagi trencat res al programari quan es modifica.

Tradicionalment, els requisits s'especifiquen en documents de requisits (per exemple, mitjançant aplicacions de processament de textos i aplicacions de fulls de càlcul). Per gestionar la complexitat creixent i la naturalesa canviant de la documentació de requisits (i la documentació de programari en general), es recomanen sistemes centrats en bases de dades i eines de gestió de requisits amb finalitats específiques.

En el desenvolupament de programari àgil, els requisits sovint s'expressen com a històries d'usuari amb criteris d'acceptació que els acompanyen. Les històries d'usuari solen formar part d'una característica o una epopeia, que és una funcionalitat més àmplia o un conjunt de funcionalitats relacionades que ofereixen un valor específic a l'usuari en funció dels requisits del negoci.

Documentació de disseny arquitectònic

La documentació d'arquitectura (també coneguda com a descripció de l'arquitectura del programari) és un tipus especial de document de disseny. En certa manera, els documents d'arquitectura són terceres derivades del codi (el document de disseny és la segona derivada i els documents de codi són la primera). Molt poca cosa en els documents d'arquitectura és específica del codi en si. Aquests documents no descriuen com programar una rutina en particular, ni tan sols per què aquesta rutina en particular existeix en la forma que existeix, sinó que simplement estableixen els requisits generals que motivarien l'existència d'aquesta rutina. Un bon document d'arquitectura és poc detallat però carregat d'explicacions. Pot suggerir enfocaments per al disseny de nivell inferior, però deixar els estudis comercials d'exploració reals per a altres documents.

Un altre tipus de document de disseny és el document de comparació o estudi comercial. Sovint pren la forma d'un document tècnic. Se centra en un aspecte específic del sistema i suggereix enfocaments alternatius. Pot ser a nivell d'interfície d'usuari, codi, disseny o fins i tot arquitectura. Descriurà la situació, descriurà una o més alternatives i enumerarà els avantatges i els inconvenients de cadascuna. Un bon document d'estudi comercial té molta recerca, expressa la seva idea amb claredat (sense dependre massa d'argot obtús per enlluernar el lector) i, el més important, és imparcial. Ha d'explicar honestament i clarament els costos de qualsevol solució que ofereixi com la millor. L'objectiu d'un estudi comercial és idear la millor solució, en lloc d'impulsar un punt de vista concret. És perfectament acceptable no establir cap conclusió o concloure que cap de les alternatives és prou millor que la línia de base per justificar un canvi. S'ha d'abordar com un esforç científic, no com una tècnica de màrqueting.

Una part molt important del document de disseny en el desenvolupament de programari empresarial és el Document de Disseny de Base de Dades (DDD). Conté elements de disseny conceptual, lògic i físic. El DDD inclou la informació formal que necessiten les persones que interactuen amb la base de dades. L'objectiu de preparar-lo és crear una font comuna que puguin utilitzar tots els actors de l'escena. Els usuaris potencials són:

• dissenyador de bases de dades
• Desenvolupador de bases de dades
• administrador de bases de dades
• Dissenyador d'aplicacions
• Desenvolupador d'aplicacions

Quan es parla de sistemes de bases de dades relacionals, el document ha d'incloure les parts següents:

• Esquema d'entitat-relació (millorat o no), incloent-hi la informació següent i les seves definicions clares:
  • Conjunts d'entitats i els seus atributs
  • Les relacions i els seus atributs
  • Claus candidates per a cada conjunt d'entitats
  • Restriccions basades en atributs i tuples
• Esquema relacional, que inclou la informació següent:
  • Taules, atributs i les seves propietats
  • Vistes
  • Restriccions com ara claus primàries, claus externes,
  • Cardinalitat de les restriccions referencials
  • Política en cascada per a restriccions referencials
  • Claus primàries

És molt important incloure tota la informació que utilitzaran tots els actors de l'escena. També és molt important actualitzar els documents a mesura que es produeixi qualsevol canvi a la base de dades.

Documentació tècnica

És important que els documents de codi associats amb el codi font (que poden incloure fitxers README i documentació de l'API) siguin exhaustius, però no tan prolixos que esdevinguin massa laboriosos o difícils de mantenir. Sovint es troben diverses guies de documentació pràctica i general específiques per a l'aplicació de programari o el producte de programari que documenten els escriptors d'API. Aquesta documentació pot ser utilitzada per desenvolupadors, provadors i també usuaris finals. Avui dia, es veuen moltes aplicacions d'alta gamma en els camps de l'energia, el transport, les xarxes, l'aeroespacial, la seguretat, l'automatització de la indústria i una varietat d'altres dominis. La documentació tècnica s'ha tornat important dins d'aquestes organitzacions, ja que el nivell d'informació bàsic i avançat pot canviar al llarg del temps amb els canvis d'arquitectura. Hi ha proves que l'existència d'una bona documentació de codi realment redueix els costos de manteniment del programari.

Els documents de codi sovint s'organitzen en un estil de guia de referència, cosa que permet a un programador cercar ràpidament una funció o classe arbitrària.

Documentació tècnica integrada al codi font

Sovint, eines com ara Doxygen, NDoc, Visual Expert, Javadoc, JSDoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText o Universal Report es poden utilitzar per generar automàticament els documents de codi — és a dir, extreuen els comentaris i els contractes de programari, quan estan disponibles, del codi font i creen manuals de referència en format de fitxers de text o HTML.

La idea de generar documentació automàticament és atractiva per als programadors per diverses raons. Per exemple, com que s'extreu del mateix codi font (per exemple, mitjançant comentaris), el programador la pot escriure mentre fa referència al codi i utilitzar les mateixes eines que s'han utilitzat per crear el codi font per fer la documentació. Això fa que sigui molt més fàcil mantenir la documentació actualitzada.

Un possible inconvenient és que només els programadors poden editar aquest tipus de documentació i depèn d'ells actualitzar la sortida (per exemple, executant una tasca cron per actualitzar els documents cada nit). Alguns qualificarien això com un avantatge més que no pas un inconvenient.

Documentació d'usuari

A diferència dels documents de codi, els documents d'usuari simplement descriuen com s'utilitza un programa.

En el cas d'una biblioteca de programari, els documents de codi i els documents d'usuari podrien ser en alguns casos equivalents i val la pena combinar-los, però per a una aplicació general això no sol ser cert.

Normalment, la documentació d'usuari descriu cada característica del programa i ajuda l'usuari a realitzar aquestes funcions. És molt important que els documents d'usuari no siguin confusos i que estiguin actualitzats. Els documents d'usuari no necessiten estar organitzats de cap manera en particular, però és molt important que tinguin un índex complet. La coherència i la simplicitat també són molt valuoses. La documentació d'usuari es considera un contracte que especifica què farà el programari. Els escriptors d'API tenen molt bona experiència a l'hora d'escriure bons documents d'usuari, ja que coneixen bé l'arquitectura del programari i les tècniques de programació utilitzades. Vegeu també escriptura tècnica.

La documentació d'usuari es pot produir en diversos formats en línia i impresos. Tanmateix, hi ha tres maneres generals d'organitzar la documentació d'usuari.

1. Tutorial: Un enfocament tutorial es considera el més útil per a un usuari nou, en el qual se'l guia a través de cada pas per dur a terme tasques particulars.
2. Temàtic: Un enfocament temàtic, on els capítols o seccions es concentren en una àrea d'interès particular, és d'ús més general per a un usuari intermedi. Alguns autors prefereixen transmetre les seves idees a través d'un article basat en el coneixement per facilitar les necessitats de l'usuari. Aquest enfocament sol ser practicat per una indústria dinàmica, com ara la tecnologia de la informació.
3. Llista o referència: L'últim tipus de principi organitzatiu és aquell en què les ordres o tasques simplement es llisten alfabèticament o agrupades lògicament, sovint mitjançant índexs amb referències creuades. Aquest darrer enfocament és més útil per als usuaris avançats que saben exactament quin tipus d'informació busquen.

Una queixa comuna entre els usuaris pel que fa a la documentació del programari és que només es va adoptar un d'aquests tres enfocaments, gairebé excloent els altres dos. És habitual limitar la documentació de programari proporcionada per a ordinadors personals a l'ajuda en línia que només proporciona informació de referència sobre ordres o elements de menú. La tasca de formar nous usuaris o ajudar els usuaris més experimentats a treure el màxim profit d'un programa es deixa a editors privats, que sovint reben una assistència important del desenvolupador del programari.

Documentació de màrqueting

Per a moltes aplicacions cal tenir materials promocionals per animar els observadors ocasionals a dedicar més temps a conèixer el producte. Aquesta forma de documentació té tres finalitats:

1. Entusiasmar l'usuari potencial amb el producte i inculcar-li el desig d'involucrar-s'hi més.
2. Informar-los sobre què fa exactament el producte, de manera que les seves expectatives estiguin en línia amb el que rebran.
3. Explicar la posició d'aquest producte respecte a altres alternatives.

Documentació i controvèrsia sobre el desenvolupament àgil

«La resistència a la documentació entre els desenvolupadors és ben coneguda i no cal emfatitzar-la.» Aquesta situació és particularment prevalent en el desenvolupament de programari àgil perquè aquestes metodologies intenten evitar qualsevol activitat innecessària que no aporti valor directament. En concret, el Manifest Àgil defensa valorar «el programari funcional per sobre de la documentació completa», que es podria interpretar cínicament com «Volem passar tot el nostre temps programant. Recordeu, els programadors reals no escriuen documentació.»

Una enquesta entre experts en enginyeria de programari va revelar, però, que la documentació no es considera en absolut innecessària en el desenvolupament àgil. Tot i això, es reconeix que hi ha problemes de motivació en el desenvolupament i que poden ser necessaris mètodes de documentació adaptats al desenvolupament àgil (per exemple, mitjançant sistemes de reputació i ludificació).