Documentacion logicielle
La documentacion logicielle es un tèxt, generalament acompanhat de capturas d'ecran, que concernís un logicial informatic. Explica coma lo logicial fonciona, e/o coma lo cal emplegar. Lo tèrme pòt aver de significacions diferentas per de personas de diferents perfils.
La documentacion constituís una partida importanta de l'engenhariá logicielle, qu'es sovent negligida[réf. necessari].
Tips de documentacion[modificar | modificar lo còdi]
La documentacion pòt èsser de mantun tip :
- L'expression de besonh - Definís lo besonh del mestièr pendent una demanda.
- Arquitectura / Concepcion - Vista d'amassa sul logicial. Inclutz las relacions a l'environament e los principis a utilizar dins la concepcion e la realizacion dels compausants logicials.
- Tecnica - Documentacion del còdi, algoritmes, interfàcias, e interfàcias de programacion (API).
- Utilizator - Manuals pels utilizators, administrators sistèmas e personal de supòrt.
- Marcatica - Instruccions sul produch e garantida promocionala.
Expression de besonh[modificar | modificar lo còdi]
Documentacion sus l'arquitectura e la concepcion[modificar | modificar lo còdi]
La documentacion sus l'arquitectura es un tip especial de documents de concepcion. D'una certana faiçon, los documents sus l'arquitectura son los tresens derivats del còdi (los documents de concepcion essent los segonds derivats, e documents sul còdi essent lo primièr). I a plan pauc de causa dins los documents sus l'arquitectura que siá especifica al còdi el meteis. Aqueles documents descrivon pas coma programar una foncion (rotina) particulara, o quitament perqué aquela foncion particulara existís jos aquela forma, mas expausa las exigéncias generalas que motivan l'existéncia d'una tala foncion. Un bon document d'arquitectura es cort suls detalhs mas dens sus l'explicacion. Pòt suggerir d'apròchis per de concepcions en mai bas nivèl, mas daissa los estudis d'exploracion efectivas a d'autres documents.
Una autra mena de documents de concepcion es lo document de comparason. Aquò pòt prene sovent la forma d'un libre blanc. Se concentra sus un aspècte especific del sistèma e suggerís d'apròchis alternatius. Aquò se pòt situar al nivèl de l'interfàcia utilizator, del còdi, de la concepcion, o quitament al nivèl de l'arquitectura. Soslinharà la situacion del "SE" (sistèma d'informacion), descriurà una o mantuna alternativa en presentant lors avantatges e inconvenients. Un bon estudi comparatiu es pesuc ne recèrca, exprimís sas idèas clarament (sens se pausar massissament sus un girgon escur per eissorbar lo legidor), e sustot es imparciala. Deu explicar onèstament e clarament los còstes de tota solucion en fàcia de çò que pòrta de melhor. L'objectiu d'un estudi comparatiu es de discernir la solucion melhora, puslèu que de possar a un ponch de vista particular. Es perfièchament acceptable d'establir pas una conclusion, o de conclure que cap de las alternativas ofrís pas d'avantatge substancial respècte a la situacion actuala per justificar un cambiament. Deu èsser concebuda coma una iniciativa scientifica, pas coma una tecnica marcatica.
Documentacion tecnica de frasas[modificar | modificar lo còdi]
S'agissent de la documentacion tecnica, conven de distinguir mantun tip de documentacion :
- la documentacion associada al logicial d'espleitacion, que fornís a l'esplechaire las instruccions d'utilizacion del material informatic (ordenador) ;
- la documentacion associada als logicials d'aplicacion (grandas foncions de l'entrepresa : finanças, crompas, logistica...), qu'indica coma utilizar lo logicial.
La màger part dels programaires emplegan l'expression « documentacion logicielle » dins lo cas d'una documentacion suls logicials d'aplicacion. Quand desvolopan de logicial, lo còdi sorsa es insufisent a el sol. I deu aver de tèxt que l'acompanha per descriure los diferents aspèctes del foncionament esperat. Aquela documentacion es abitualament inclusa dins lo còdi sorsa per tal d'èsser aisidament accessible a qual que siá seriá menat a o córrer.
Aquel document escrich pòt èsser nautament tecnic, e es principalament utilizat per definir e explicar las interfàcias de programacion (APIs), las estructuras de donadas e los algoritmes. Per exemple, se pòt utilizar aquela documentacion per explicar que la variable m_name se referís al primièr e al darrièr nom d'una persona. Es important pels documents sul còdi d'èsser precís, mas pas tanpauc verbós a un ponch tal coma seriá dificil d'o mantenir.
Sovent los generators de documentacion coma Esfinx, Doxygen o Javadoc pòdon èsser utilizats per generar automaticament la documentacion del còdi sorsa del logicial ; tiran los comentaris del còdi sorsa e crèan de manuals de referéncia al format HTML o PDF. Los documents generats son sovent organizats dins l'estil d'un guida de referéncia, çò que permet a un programaire de localizar lèu una foncion o una classa quala que siá.
Fòrça programaires aprècian la documentacion automatica del còdi sorsa, particularament perque li permet de l'escriure en se referissent a son còdi e d'utilizar los meteisses espleches que per escriure lo còdi. Aquò facilita la sincronizacion entre lo còdi sorsa e la documentacion.
L'inconvenient es que sols los programaires pòdon editar aquel tip de documentacion, e es d'eles que depend l'actualizada de las sortidas (per exemple, en executant un crontab per actualizar los documents la nuèch). D'unes considèran aquò coma un avantatge puslèu que coma un inconvenient.
Donald Knuth a insistit sul fach que la documentacion pòt èsser un procediment plan dificil de reflexion après còp e a recomandat la programacion letrada, que consistís a escriure la documentacion a l'encòp e quitament endrech que lo còdi sorsa e a lo tirar per de mejans automatics.
Documentacion utilizator[modificar | modificar lo còdi]
A la diferéncia de la documentacion tecnica, los documents utilizators son generalament pro alunhats del còdi sorsa del programa, e descrivon simplament coma es emplegat.
Dins lo cas d'una bibliotèca logicielle, los documents sul còdi e los documents utilizators poirián efectivament èsser coblats e aquò val la pena de los regropar, mas aquò es pas totjorn valable per las aplicacions en general.
La maquina Lisp a seguit la tradicion segon la quala cada element de còdi aviá un camp de documentacion estacat. En relacion amb las fòrtas capacitats de recèrca (basadas sus una comanda apropriada assimilada a Unix), e de las fonts en linha, los utilizators de Lisp podián consultar la documentacion e reprene la foncion associada dirèctament dins lor pròpri còdi. Aquel nivèl de facilitat es desconegut de sistèmas presumits mai modèrns.
Tipicament, la documentacion utilizators descriu cada caracteristica del programa, e las diferentas etapas necessàrias per lo cridar. Un bon document utilizator pòt tanben anar fins a fornir una assisténcia menimosa en linha. Es plan important que los documents utilizators sián pas confuses, e que sián a jorn. Los documents utilizators an pas besonh d'èsser estructurats d'una faiçon particulara, mas es plan important qu'ajan un indèx precís. La coeréncia e la simplicitat son tanben doas qualitats plan preciosas. Se considèra que la documentacion utilizator constituís un contracte qu'especifica çò que lo logicial deu far.
I a tres grandas faiçons d'organizar la documentacion utilizator :
- Tutorial
- Se considèra qu'un apròchi per tutorial es lo mai util per un utilizator novèl. Dins aquel metòde l'utilizator es guidat a cada etapa de compliment de las tascas particularas amb l'ajuda de capturas d'ecran e d'instruccions.
- Tematica
- Per un utilizator intermediari, s'emplega generalament un apròchi tematic, dins la quala los capítols o seccions se concentran sus un domeni d'interès particular.
- Lista
- Lo tip final de principi d'organizacion es lo dins lo qual las comandas o las tascas son simplament listadas per òrdre alfabetic, sovent per d'indicis crosats. Aquel darrièr apròchi es d'un interès plan naut per d'utilizators avançats que coneisson exactament quala mena d'informacion recercan. Un grèuge universalament exprimit pels utilizators a prepaus de la documentacion logicielle es qu'adòpta pas que l'una d'aqueles tres apròchis a l'exclusion dels dos autres.
Dins lo cas dels micro-ordenadors, es frequent de limitar la fornidura de documentacion logicielle a l'ajuda en linha, que se limita a d'informacions de referéncia sus las comandas o las linhas de menut. Lo trabalh d'ensenhament de novèls utilizators o d'ajuda a d'utilizators mai experimentats a tirar lo partit melhor d'un programa es daissat a de publicateurs privats, a que lo desvolopaire del logicial balha una assisténcia significativa.
Documentacion marcatica[modificar | modificar lo còdi]
Per fòrça aplicacions, fa besonh de dispausar de materials promocionals per incitar dels observators ocasionals a passar mai de tempses a s'interessar al produch.
Aquela forma de documentacion a tres objectius :
- Incitar los utilizators potencials a s'interessar al produch e installar lo desir de s'implicar mai dins lo produch.
- Informar l'utilizator sus çò que fach exactament lo produch, de manièra que lors espèras sián en fasa amb çò que van recebre.
- Explicar la posicion d'aquel produch respècte a d'autras alternativas.
Una bona tecnica de marcatica es de fornir de frasas de penja claras e mémorisables qu'illustran lo ponch que se desira transmetre, e tanben metre l'accent sus l'interopérabilité del programa amb d'autres produches.
Espleches e metòdes[modificar | modificar lo còdi]
Cicle de vida del logicial[modificar | modificar lo còdi]
- Arquitectura : quadre d'arquitectura (Quadre Zachman, TOGAF, DoDAF, MODAF, AGATE)
- Concepcion : UML, SysML, BPML...
- Realizacion : BPEL...
Engèni logicial e documentacion[modificar | modificar lo còdi]
Emplec de la lenga francesa[modificar | modificar lo còdi]
Dins lo cas ont i a un contracte amb un consumaire, e per tot organisme regit per la lei francesa, la lei relativa a l'emplec de la lenga francesa s'aplica (lei comunament apelada lei Toubon, 1994).
En 1996, una circulara precisava que lo mòde d'emplec dels logicials d'aplicacion e d'espleitacion deviá èsser redigit en francés.
Las licéncias de logicial pòdon èsser mai o mens concebudas en foncion dels besonhs de documentacion logicielle.
Cas de fornidura de material informatic[modificar | modificar lo còdi]
La fornidura de material informatic es abitualament assortida de la fornidura de la documentacion logicielle associada qu'indica al personal esplechant las instruccions que permeton d'emplegar lo material informatic.
Cas del logicial liure[modificar | modificar lo còdi]
La licéncia GNU/FDL de la Free Logicial Foundation es estada pensada e creada per la documentacion associada al logicial, es plan largament utilizada per la documentacion del logicial liure, mas pas unicament.
La cession de dreches (concretizada per una licéncia) es un contracte al sens juridic, la lei Toubon s'aplica dins la mesura ont l'organisme es regit per la lei francesa.
Contraròtles d'aplicacion de la lei[modificar | modificar lo còdi]
Es la DGCCRF qu'es cargada de procedir als contraròtles d'aplicacion de la lei. La Comission dels afars culturals demanda a çò qu'una circulara pòsca portar « las clarificacions necessàrias a la bona aplicacion de la lei sus l'emplec de la lenga francesa dins l'univèrs numeric », sustot per poder afortir lo quadre dins lo qual se degan inscriure los contraròtles de la DGCCRF.
