Una bona documentació de programari, ja sigui documentació d’especificacions per a programadors i verificadors, documents tècnics per a usuaris interns o manuals i fitxers d’ajuda per a usuaris finals, ajudarà els usuaris a entendre les funcions i funcions del programari. Una bona documentació és documentació específica, clara i rellevant, amb tota la informació que l'usuari necessita. Aquest article us guiarà a escriure documentació de programari per a usuaris tècnics i usuaris finals.
Pas
Mètode 1 de 2: escriptura de documentació de programari per a usuaris tècnics
Pas 1. Conegueu quina informació voleu incloure
El document d'especificacions s'utilitza com a manual de referència per a dissenyadors d'interfícies, programadors que escriuen codi i verificadors que verificen el rendiment del programari. La informació que cal incloure dependrà del programa que es creï, però pot incloure el següent:
- Fitxers importants de l'aplicació, com ara fitxers creats per l'equip de desenvolupament, bases de dades a les quals s'ha accedit mentre s'executa el programa i aplicacions de tercers.
- Funcions i subrutines, inclosa una explicació de l'ús de la funció / subrutina, els valors d'entrada i sortida.
- Programa variables i constants i com s’utilitzen.
- Estructura general del programa. Per als programes basats en unitats, és possible que hagueu de descriure cada mòdul i biblioteca. O bé, si escriviu un manual per a un programa basat en web, potser haureu d'explicar quins fitxers utilitza cada pàgina.
Pas 2. Decidiu quin nivell de documentació ha de ser present i separable del codi del programa
Com més documentació tècnica s’inclogui al codi del programa, més fàcil serà actualitzar-lo i mantenir-lo, així com explicar les diferents versions del programa. Com a mínim, la documentació del codi del programa ha d’incloure l’ús de funcions, subrutines, variables i constants.
- Si el vostre codi font és llarg, podeu escriure documentació en un fitxer d’ajuda, que després es pot indexar o cercar amb determinades paraules clau. Els fitxers de documentació separats són útils si la lògica del programa es divideix en diverses pàgines i inclou fitxers de suport, com ara una aplicació web.
- Alguns llenguatges de programació (com Java, Visual Basic. NET o C #) tenen els seus propis estàndards de documentació de codi. En aquests casos, seguiu la documentació estàndard que cal incloure al codi font.
Pas 3. Seleccioneu l'eina de documentació adequada
En alguns casos, l'eina de documentació ve determinada pel llenguatge de programació utilitzat. Els llenguatges C ++, C #, Visual Basic, Java, PHP i altres tenen les seves pròpies eines de documentació. No obstant això, si no, les eines utilitzades dependran de la documentació requerida.
- Un processador de textos com Microsoft Word és adequat per crear fitxers de text de document, sempre que la documentació sigui concisa i senzilla. Per crear documentació llarga amb text complex, la majoria dels redactors tècnics trien una eina de documentació especialitzada, com ara Adobe FrameMaker.
- Els fitxers d’ajuda per documentar el codi font es poden crear amb un programa generador de fitxers de suport, com ara RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare o HelpLogix.
Mètode 2 de 2: escriptura de documentació de programari per a usuaris finals
Pas 1. Conegueu els motius empresarials subjacents a la creació del manual
Tot i que el motiu principal de la documentació del programari és ajudar els usuaris a entendre com utilitzar l’aplicació, hi ha altres motius que poden estar a la base de la creació de la documentació, com ara ajudar al departament de màrqueting a vendre l’aplicació, millorar la imatge de l’empresa i reduir l’assistència tècnica. costos. En alguns casos, es requereix documentació per complir la normativa o altres requisits legals.
Tot i això, la documentació no és un bon substitut d'una interfície. Si una aplicació requereix molta documentació per funcionar, s'hauria de dissenyar per ser més intuïtiva
Pas 2. Conegueu el públic objectiu de la documentació
En general, els usuaris de programari tenen coneixements informàtics limitats més enllà de les aplicacions que utilitzen. Hi ha diverses maneres de satisfer les seves necessitats de documentació:
- Presteu atenció al títol de l'usuari del programari. Per exemple, l'administrador del sistema sol entendre diverses aplicacions informàtiques, mentre que el secretari només coneix les aplicacions que utilitza per introduir dades.
- Presteu atenció als usuaris de programari. Tot i que les seves posicions són generalment compatibles amb les tasques realitzades, aquestes posicions poden tenir càrregues de treball diferents, en funció del lloc de treball. En entrevistar usuaris potencials, podeu esbrinar si la vostra avaluació del seu lloc de treball és correcta.
- Presteu atenció a la documentació existent. La documentació i les especificacions de la funcionalitat del programari poden mostrar el que els usuaris han de saber per utilitzar-les. Tot i això, tingueu en compte que és possible que els usuaris no estiguin interessats a conèixer les "entranyes" del programa.
- Conegueu què es necessita per completar una tasca i què es necessita abans de poder completar-la.
Pas 3. Determineu el format adequat per a la documentació
La documentació del programari es pot disposar en 1 o 2 formats, és a dir, llibres de consulta i manuals. De vegades, combinar els dos formats és una bona solució.
- Els formats de referència s’utilitzen per descriure totes les funcions del programari, com ara botons, pestanyes, camps i quadres de diàleg, i com funcionen. Alguns fitxers d’ajuda s’escriuen en aquest format, especialment aquells que són sensibles al context. Quan l’usuari faci clic a Ajuda en una pantalla determinada, l’usuari rebrà el tema rellevant.
- El format manual s’utilitza per explicar com fer alguna cosa amb el programari. Els manuals solen estar en format imprès o PDF, tot i que algunes pàgines d’ajuda també inclouen instruccions sobre com fer determinades coses. (Generalment, els formats manuals no són sensibles al context, però poden estar enllaçats a partir de temes contextuals). Els manuals solen tenir la forma d’una guia, amb un resum de les tasques a realitzar en una descripció i una guia formatada per passos.
Pas 4. Decidiu el tipus de documentació
La documentació del programari per als usuaris es pot incloure en un o més dels formats següents: manuals impresos, fitxers PDF, fitxers d’ajuda o ajuda en línia. Cada tipus de documentació està dissenyada per mostrar-vos com utilitzar les funcions del programari, ja sigui una guia o un tutorial. La documentació i les pàgines d’ajuda en línia també poden incloure vídeos de demostració, text i imatges estàtiques.
Els fitxers d’ajuda i assistència en línia s’han d’indexar i fer cerques mitjançant paraules clau perquè els usuaris puguin trobar ràpidament la informació que necessiten. Tot i que una aplicació generadora de fitxers d’ajuda pot crear un índex automàticament, encara es recomana crear manualment un índex mitjançant paraules clau que es cerquen habitualment
Pas 5. Seleccioneu l'eina de documentació adequada
Es poden crear manuals o PDF impresos amb un programa de processament de textos com Word o un editor de text avançat com FrameMaker, en funció de la longitud i la complexitat del fitxer. Els fitxers d’ajuda es poden escriure amb un programa de creació de fitxers d’ajuda, com ara RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix o HelpServer.
Consells
- El text de la documentació del programa s’ha d’estructurar de manera que sigui fàcil de llegir. Col·loqueu la imatge el més a prop possible del text adequat. Desglosseu la documentació per seccions i temes lògicament. Cada secció o tema hauria de descriure un problema específic, tant de les tasques com de les funcions del programa. Els problemes relacionats es poden explicar amb enllaços o llistes de referències.
- Cadascuna de les eines de documentació descrites en aquest article es pot complementar amb un programa de fabricació de captures de pantalla, com ara SnagIt, si la vostra documentació requereix diverses captures de pantalla. Com qualsevol altra documentació, també heu d'incloure captures de pantalla per ajudar a explicar el funcionament de l'aplicació, en lloc de "atraure" l'usuari.
- Prestar atenció a l’estil és molt important, sobretot si escriviu documentació de programari per a usuaris finals. Adreçeu-vos als usuaris amb el pronom "tu", en lloc de "usuari".
