Est ándarI EEESt d10632001,par adocument aci ón deusuar i os "Contar con un estandar para la documentación de usuarios de software es necesario. El Std 1063-2001 ofrece una buena gua para crear un manual de usuario adecuado"
!ucos de nosotros nos encontramos en el #rea de la documentación de sistemas $al menos fue mi caso% por coincidencia. &a primera 'es (ue uno tiene un acercamiento con el #rea tiene una noción de los documentos (ue deben ser parte de un desarrollo o produc producto to de softw software are)) pero pero sin embar embargo go descon desconoce oce (u* (u* partes partes o secci seccione oness debe debe contener esos documentos. +or e,emplo (u* secciones debe tener un manual de usuario) o una memoria t*cnica) etc. El est#ndar /EEE std 1063-2001 brinda ese marco de referencia para establecer (u* partes deben conformar cual(uier documento (ue deba ser utiliado por un usuario del sistema o programa en cuestión. Este est#ndar solo se aplica a la documentación de usuario) para la documentación de car#cter t*cnico se utilian otras recomendaciones de las cuales ablaremos en su momento. grandes rasgos la recomendación del /EEE establece las siguientes partes para un documento (ue usar#n los usuarios. Estas partes son 1.- /dentificación de los datos $pa(uete) ttulo% 2.- abla de contenidos) en documentos con m#s de 4 p#ginas 3.- &ista de ilustraciones ilustraciones $optati'o% 5.- /ntroducción .- /nformación para el uso de la documentación 6.- Conceptos de las operaciones 7.- +rocedimientos 4.- /nformación sobre los comandos de software 8.- !ensa,es de error 9 resolución de problemas 10.- :losario
11.- ;eferencias 12.- Caractersticas de na'egación na'egación 13.- erramientas de b?s(ueda $en documentos electrónicos% electrónicos%
¿Qué es la documentación? "Pensemos en nombres como los de Leonardo Da Vinci, Isaac Newton, Galileo o algún otro. Todos sabemos que han hecho ero, !caso odr#amos acordarnos de ellos si no tu$iera tu$i eramos mos registro de sus ideas o de sus in$enciones%." En el caso de los grandes pensadores) mu,eres 9 ombres) de la umanidad su legado a (uedado plasmado plasmado en libros) esto es su obra 9 pensamiento pensamiento a sido documentado. &a documentación tiene su fundamento en el m*todo cientfico. Con la intención de poder replicar el o los e=perimentos realiados para 'alidar alguna tesis) el cientfico regis registra tra todas todas las condicio condicione ness ba ba,o ,o las las cuale cualess se reali realiaa el e=per e=perime imento nto)) de igual igual mane manera ra los los resu result ltad ados os se escr escrib iben en en tabl tablas as 9 esta estass a su 'e 'e gene genera rann gr#f gr#fic icos os estadsticos (ue nos permiten interpretarlos. En la actualidad los medios para lle'ar el registro de alguna acti'idad son mu9 di'ersos) siendo los digitales los m#s utiliados en la actualidad. ora bien definiremos a la documentación como el proceso de registrar de manera ordenada los procedimientos 9 resultados obtenidos a lo largo de una in'estigación cientfica o pro9ecto o en general cual(uier acti'idad (ue se necesite repetir m#s de una 'e) por e,emplo una receta de cocina bien documentada deber# lle'ar el tiempo e=acto de cocción 9 la temperatura e=acta en la (ue el platillo obtiene sus me,ores propiedades. @ocumentar nos permite dar el salto entre lo emprico 9 lo cientfico) entre el aar 9 las me,ores pr#cticas. @ocumentar un sistema de información implica almacenar 9 organiar la información necesaria $en forma de documento escrito o gr#fico% con la intención de (ue al terminar el pro9ecto podamos mantenerlo) me,orarlo 9Ao repetirlo. &a cantidad de documentos generados a lo largo del pro9ecto 'a a depender del e(uipo (ue constru9e el software 9 del o los marcos de desarrollo (ue utilice la organiación. dem#s en el caso caso de pro9ec pro9ectos tos empres empresari ariale aless se deber# deber# guard guardar ar docume documenta ntació ciónn inclu incluso so de la configuración configuración del ardware donde se despliegan los sistemas construidos.
@e lo anterior me atre'era a dar la siguiente Clasificación de la @ocumentación 1. Documentación administrativa:
Se refiere a los documentos (ue forman parte del conte=to de la administración del pro9ecto como tal +lanes de traba,o) @efinición del pro9ecto) @efinición de roles 9 perfiles de los integrantes del pro9ecto. n#lisis de costos) n#lisis de riesgos) etc. En este lugar) por e,emplo) podramos colocar todos los documentos de la gestión de pro9ectos (ue establece el +!BD. 2. Documentación técnica:
a% @esarrollo de software. En este este ap apar arta tado do pued pueden en colo coloca cars rsee los los docu docume ment ntos os rela relaci cion onad ados os con con el cicl cicloo de desarrollo del sistema. @e igual manera la cantidad de documentos 'aria de acuerdo al fra framew mewor uti utiliad iadoo pa para ra crear rear el prod produc ucto to de soft softwa ware re.. En el caso caso de una apro=imación cl#sica donde se define al ciclo de 'ida de los sistemas como n#lisis) @esarrollo) +ruebas e /mplementación) tendramos documentos tales como Cat#logo de re(uerimientos) digramas F!&) Solución propuesta) @iccionario de @atos) @iccionario de formularios) Cat#logo de ob,etos) Código fuente comentado) +lan de pruebas) pruebas 9 resultados) +lan de implementación o implantación) !emoria de instalación) !anual de usuario) !anual de administración. Fn marco m#s agil como SC;F!) no consideraria tantos documentos en su lugar considerara m#s (ue suficiente (ue el código se comente de acuerdo al estandar del lengua,e) lengua,e) por e,emplo en Ga'a se deber# utiliar el formato Ga'a@oc. b% plicati'os utiliados. En el caso de aplicaciones empresariales donde adem#s de desarrollar software a la medida se utilian algunos programas (ue 9a son comercialiados) debemos guardar la memoria de instalación de los di'ersos aplicati'os (ue forman la plataforma. plataforma. c% Componentes de ardware Se debe guardar registro de la configuración del ardware sobre el cual se est# instalando el aplicati'o) debemos recordar (ue lo (ue deseamos es replicar el proceso m#s 'eces) por lo (ue la omisión de la configuración (ue tiene el ardware puede ser crucial para obtener los resultados esperados.
3. +rocesos. ener escritos los procesos con base a est#ndares permitir# a las empresas e'aluarlos 9 me,orarlos. &os procesos del cliente nos sir'en para adecuar el producto de software a la empresa. &a empresa (ue desarrolla el software o (ue ofrece ser'icios de / puede encontrar un gran apo9o en marcos de referencia como //&. Hamos a cerrar el tema considerando lo siguiente 1 &a documentación documentación permite repetir repetir el ciclo de desarrollo del del sofware 2 +ermite +ermite la me,ora continua 3 Establece las las bases del conocimiento conocimiento del del negocio 5 !arca el estandar de calidad del del software +ermite +ermite medir el el a'ance del pro9ecto 6 Establece un legado legado para la siguiente siguiente generación de desarrollado desarrolladores res Iinalmente considero (ue cual(uier pro9ecto de software de mediana a gran escala) (ue no est* bien documentado est# condenado al fracaso 9 al ol'ido. +or otro lado no e=iste una lista de documentos estandar) en todo caso la lista de documentos dependen de las las meto metodo dolo log gas as 9 marc marcos os de refe refere renc ncia ia util utili iad ados os en su desa desarr rrol ollo lo 9 de las las indicaciones del personal directi'o) esto es (u* (uiero (ue se documente) de un producto en especfico.
¿Cómoescr i bi runmanualdeusuar i o? "Conocer a detalle el proceso o sistema para el cual se re(uiere el manual) es la columna 'ertebral de toda buena documentación de usuario" &ecomendaciones &ecomendaciones ara escribir un manual de usuario
El proceso de creación de un manual de usuario es cosa sencilla siempre 9 cuando se tenga en cuenta algunos puntos) los cuales deben seguirse en secuencia para no perdernos. El primer paso para escribir el manual sera Identi'icar al usuario de la documentaci(n o (uienes ser#n los lectores potenciales del documento. Esto nos a9udar# a ubicar cu#l es el ni'el t*cnico (ue se deber# utiliar en el documento 9 de alguna manera a planter su contenido. El segu segund ndoo pa paso so ser# ser# de Jecesi sita tamo moss sabe saberr (ue (ue de'i 'ini nirr su ta tabl bla a de co cont nten enid idos os. Jece
información ser# colocada en *l 9 en (u* órden. Fna buena pr#ctica es colocar la tabla de contenidos en una matri) en una o,a de c#lculo) para ir seKalando el a'ance de cada tema o proceso 9 de esa manera conocer el a'ance de lo (ue 'amos escribiendo 9 su relación. ercero )rgani*ar el contenido. Fna pregunta recurrente es (u* se debe colocar en un manual de usuario o cómo se debe organiar. Bien 9o utilió dos apro=imaciones Colocar en el ndice los casos de uso 9 clasificarlos de acuerdo a los usuarios (ue los utilian o organiar la información por funcionalidad. funcionalidad. +or e,emplo) supongamos (ue se diseKo un programa de punto de 'enta 9 algunos de sus casos de uso son 7 Dar de de alta un product producto o 8 Modificar Modificar el precio del producto producto 9 Inici Iniciar ar venta venta 10 Terminar venta 11 evisar e!istencias
+ues bien puede colocarse una lista con los casos de uso 9 comenar a describirlos o podemos organiar el ndice de acuerdo a las funcionalidades o a los procesos (ue se pueden realiar en el sistema) por e,emplo
1 eali"ar una venta venta #este proceso se$uro se$uro necesita incluir incluir los casos de uso Iniciar venta venta % terminar venta& 2 evisar inventario inventario #en este proceso proceso 'ui"a se necesite necesite car$ar nuevos productos productos o modificar el precio de al$uno % revisar las e!istencias en el almacen&. Cuarto &ecoilar + clasi'icar la in'ormaci(n para cada tema o subtema dentro del
documento. un(ue este punto se coloca en el cuarto lugar es indispensable (ue contemos con un almacen de información antes de la elaboración del documento. Contar con un repositorio de información nos brinda la posibilidad posibilidad de tener un almacen centraliado centraliado de información) para (ue buscarla 9 clasificarla sea m#s facil. $puedes 'er como instalar SHJ en tu organiación en el siguiente lin lin..
Fna 'e (ue emos emos cumpli cumplido do con los cuatro cuatro puntos puntos anterio anteriores res debemo debemoss elegir una estructura o marco de re'erencia formal para nuestro manual. @e manera personal utilio como referencia el estandar /EEE std-1063-2001. En el se especifican las partes (ue debe contener cual(uier documentación de usuario.
ora si debemos comen*ar a escribir el manual) aun(ue antes debemos decidir en (u* formato 9 con (u* software ser# creado) mi recomendación es @ocBoo $puedes 'er m#s información de su uso en el siguiente tutorial de @ocBoo%. @ocBoo%. @ebe considerarse (ue un manual esta diseKado para diferentes perfiles de usuario) as (ue a'eces con'iene realiar diferentes 'ersiones para (ue el actor en turno pueda e,ecutar todas las funciones (ue permita su perfil. +or lo tanto debe ser claro 9 descripti'o) es decir) no de,ar nada a la imaginación) ni a las suposición del usuario) de,ar claras las notas o prere(uisitos (ue el usuario re(uerir# para e,ecutar el procedimiento sin problemas)
deber# contener im#genes claras 9 detalladas las cu#les deber#n colocarse en un ndice 9 contar con una descripción de la imagen. Fn 'e (ue el manual se a terminado deber# ser e'aluado 9 re'isado por los programadores o los ingenieros de pruebas con la intención de 'alidar (ue sus indicaciones son adecuadas 9 conducen a un resultado e=itoso si se siguen al pie. Es seguro (ue escribir un manual o cual(uier documento t*cnico re(uieren) de (uien lo escribe) abilidades) abilidades) destresas 9 conocimientos sólidos sobre la gram#tica) redacción 9 ortografa con la finalidad de (ue este bien eco. Se debe recordar adem#s (ue una buena documentación) en este caso un buen manual) puede acer la diferencia entre el *=ito o el fracaso del sistema en su implementación.
Document aci ónmí ni madeunpr oyect odesof t war e "La documentaci(n de un ro+ecto es una arte esencial de las acti$idades que se deben reali*ar ara el correcto desarrollo, imlementaci(n + mantenimiento del mismo." !u- documentaci(n debe tener el sistema%
Fna de las primeras cuestiones (ue debe acer un documentador es conocer el #rea) tareas (ue estar#n ba,o su responsabilidad 9 las particularidades del pro9ecto. &a siguiente definición de wiipedia nos presenta un 'istao a lo (ue el @ocumentador de sistemas se 'a a enfrentar "En sentido restringido) la documentaci(n como ciencia documental se podra definir $a gran grande dess rasg rasgos os%% como como la cien cienci ciaa del del proc proces esam amie ient ntoo de la infor nforma maci ción ón)) (ue (ue proporciona información sobre algo con un fin determinado) de #mbito multidisciplinar o interdisciplinar. Siguiendo a Iuentes 9 +u,ol se puede seKalar a la @ocumentación como una ciencia au=iliar e instrumental. ambi*n es una ciencia en si misma 9 una de las finalidades primordiales de la @ocumentación es informar.1 falta de un consenso) a9 di'ersos autores) autores) como Guan ;os :arca o :arca o Gos* &ópe Lepes) Lepes ) (ue la consideran una ciencia $documental%) a la 'e (ue una disciplina) no sólo una t*cnica. ambi*n pueden considerarse) en sentido general) las ciencias de la documentación 9 la documentación como sinónimos) si el conte=to no perturba la intención del emisor) es decir) si no se distorsiona el mensa,e del interlocutor por(ue no se d* ambigMedad sem#ntica." +ara +a ra //& H3 el conocimient conocimientoo (ue poseen poseen los colabora colaboradore doress $conocim $conocimient ientoo propio propio o propietario% 9 (ue an ido ganando a lo largo del tiempo) no sir'e si no se adapta a est#n est#ndar dares es 9 se social socialia ia.. Siempr Siempree ser# ser# recome recomenda ndable ble docume documenta ntarr los proce procesos sos))
apegarse a est#ndares de la industria 9 e'itar (ue el conocimiento del negocio se acumule en solo algunas personas. &a documentación del pro9ecto de / debe adecuarse a las necesidades establecidas 9 a la metodologa o marco de referencia sobre el (ue se este desarrollando. Sin embargo e=isten documentos documentos fundamentales de acuerdo a la etapa o ciclo de 'ida del sistema en (ue se encuentre. El +!BD por e,emplo) establece la documentación administrati'a 9 de control (ue debe asociarse al pro9ecto. //& nos da una idea de la documentación (ue debe e=istir para proporcionar los ser'icios de manera adecuada. tros est#ndares especficos para la codificación como Ga'a@oc o de documentación de usuario propuestos por el /EEE) deben ser establecidos por el documentador documentador 9 seguidos por los programadores. programadores. &as metodologas de desarrollo de software brindan una gua de la documentación (ue es necesaria tener) aun(ue de manera general siempre se re(uerir# crear el cat#logo de re(uerimientos) diccionario de datos) diagramas F!&) el plan de traba,o) el plan de implementación o implantación) el plan de capacitación 9 el control de cambios. @epe @epend ndie iend ndoo del del leng lengua ua,e ,e en el cual cual se esta esta desa desarr rrol olla land ndoo el pro9 pro9ec ecto to se debe debe establecer el patrón de documentación por e,emplo Ga'a@oc) GS@oc) GSJ) +>+) etc. El siguiente diagrama muestra las diferentes etapas 9 #reas de un pro9ecto de / 9 los documentos asociados a cada una de ellas
Iinalmente Iinalmente todos los arci'os inclu9endo la documentación de usuario ) administrati'a) administrati'a) presupuestal 9 procedimientos) deben colocarse en un repositorio ba,o el cual se tenga un control de 'ersiones. @e manera personal recomiendo el uso de SHJ Sub'ersion o :it) aun(ue e=isten mucos m#s. Fna 'e (ue se a establecido el ambiente para el almacenamiento 9 control de la documentación 9 despu*s de determinar cuales ser#n los documentos (ue an de real reali iar arse se a lo larg largoo del del pro9 pro9ec ecto to)) debe debe dete determ rmin inar arse se el form format atoo en (ue (ue ser# ser#nn capturados 9 distribuidos. Estos formatos pueden ser formatos en Nord u alg?n otro procesador de te=to) &ae=) @ocBoo) etc.
