Como realizar documentación de software correctamente

Guía paso a paso para realizar una documentación de software

La  documentación de software, como un documento de especificaciones para programadores, un documento técnico para usuarios internos o documentos de ayuda para usuarios finales, le permite a una persona trabajar con el software de una manera más cómoda, hace que este pueda comprender las características y funciones.

documentación de software

documentación de software

Una buena documentación de usuario es específica, concisa, y relevante, y le ofrece información importante a la persona que utiliza el software. A continuación te mostramos como realizar una adecuada documentación que ayude a tus usuarios finales.

¿Qué tipo de información debes de incluir?

La documentación de software sirve como manual de consulta para que el usuario pueda verificar las funcionalidades del software. La información exacta depende del programa en cuestión, pero puede incluir cualquiera de las siguientes cosas:

Archivos importantes dentro de la aplicación. Esto puede incluir los archivos creados por el equipo de programadores, las bases de datos a las que accede el programa en funcionamiento, y los programas utilitarios de terceros.

Funciones y subrutinas. Esto incluye una explicación de lo que hace cada subrutina o función, incluyendo los alcances de sus valores de entrada y de salida.

Las variables y constantes de programa, y cómo se utilizan en la aplicación.

La estructura general del programa. Para una aplicación que funciona en el disco rígido, quizás sea necesario describir los módulos individuales y las librerías del programa, mientras que para una aplicación de internet, quizás sea necesario describir qué páginas utilizan cuáles archivos.

Tienes que decidir que parte de la documentación estará dentro del código y cual no estará.

La documentación dentro del código fuente debe explicar el propósito de las funciones, subrutinas, variables y constantes. Si el código fuente es muy largo, puede ser documentado en forma de un archivo de ayuda, el cual puede estar indexado o puede permitir búsquedas a través de palabras claves. Esto es muy ventajoso para las aplicaciones en las que la lógica del programa se encuentra fragmentada a lo largo de varias páginas e incluye una cantidad de archivos complementarios, como sucede con algunas aplicaciones de internet.

Existen lenguajes de programación, como Java y la infraestructura digital (framework) .NET (Visual Basic.NET, C #), que tienen sus propias normas para documentar el código. En estos casos, sigue las normas acerca de cuánto de la documentación debe incluirse con el código fuente.

Debes de elegir la herramienta correcta para la documentación

En ocasiones la herramienta va a depender del lenguaje con el que esté escrito el código, ya sea C++, C#, Visual Basic, Java o PHP, ya que existen herramientas específicas para estos y otros lenguajes. En otros casos, la herramienta a utilizar se determina dependiendo del tipo de documentación que sea necesario.

El programa Microsoft Word es adecuado para crear archivos de texto de la documentación por separado, siempre y cuando la documentación sea bastante corta y simple. Para archivos de texto largos y complejos, muchos escritores técnicos prefieren herramientas de documentación como Adobe FrameMaker.

Se pueden crear archivos de ayuda para documentar el código fuente utilizando cualquier herramienta para crear archivos de ayuda, como RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, or HelpLogix.

Definir los fines comerciales de tu documentación

EL motivo principal por lo que se documenta el software es ayudar a los usuarios a entender cómo usar la aplicación, también existen otros motivos, como asistir al marketing del software, mejorar la imagen de la compañía, y más importante, reducir los costos de soporte técnico.

Existen algunos casos, donde la documentación es necesaria para cumplir con ciertas regulaciones o requerimientos legales. Sin embargo, la documentación de software jamás debe compensar por un mal diseño de interfaz. Si una pantalla de la aplicación requiere páginas y páginas de documentación que la expliquen, es mejor cambiar el diseño de la pantalla y hacer algo más intuitivo.

Saber para quien estará dirigida la documentación

En la mayoría de los casos, los usuarios de software saben poco acerca de computadoras fuera de las tareas que les permite realizar las aplicaciones que utilizan. Existen varios modos de determinar cómo satisfacer sus necesidades con la documentación.

Observa los títulos profesionales que tienen tus posibles usuarios. Un administrador de sistemas posiblemente sea experto en varios programas de computación, mientras que un empleado que ingresa datos posiblemente conozca únicamente la aplicación que utilice en ese momento para ingresar los datos.

Observa a los usuarios en sí. Aunque los títulos profesionales por lo general indican qué es lo que hacen las personas, pueden haber variaciones considerables en cómo algunos títulos se utilizan en ciertas organizaciones. Al entrevistar a los posibles usuarios, puedes tener una idea de si estás en lo cierto respecto a lo que piensas que indica su título profesional

Observa la documentación existente. La documentación de las versiones anteriores del software, así como las especificaciones funcionales, proporcionan algunas indicaciones acerca de lo que el usuario necesitará para saber cómo utilizar el programa. Sin embargo, ten en cuenta que a los usuarios finales no les interesa cómo funciona el programa, sino qué es lo que el programa puede hacer por ellos.

Identifica las tareas necesarias para realizar el trabajo, y qué tareas deben realizarse antes de que las otras tareas puedan llevarse a cabo.

Selecciona el formato apropiado para tu documentación

A veces, el mejor enfoque es utilizar una combinación de ambos formatos.

Un manual de consulta se dedica a explicar las características individuales de un software (botón, barra, campo, y cuadro de diálogo) y cómo funcionan.

Muchos archivos de ayuda están escritos utilizando este formato, en especial los archivos de ayuda que se tienen en cuenta el contexto y muestran un tema relevante cuando el usuario hace clic en el botón de Ayuda en una pantalla en particular.

Un formato de guía de usuario explica cómo se usa el software para realizar una tarea en particular. Las guías de usuario, por lo general, vienen impresas o en PDF, aunque algunos archivos de ayuda incluyen temas acerca de cómo realizar tareas específicas (por lo general, estos temas de ayuda no tienen en cuenta el contexto, aunque pueden estar vinculados con otros temas que sí lo tengan).

Decide qué forma debería tomar la documentación

La documentación de software para usuarios finales puede tomar una entre varias formas: manuales impresos, documentos PDF, archivos de ayuda, o ayuda en línea. Cada una de las formas está diseñada para mostrarle al usuario cómo usar cada función del programa, ya sea en forma de guía paso a paso o de tutorial.

Tips

El texto debe estar organizado de manera que pueda leerse fácilmente, con las imágenes colocadas lo más cerca posible al texto que haga referencia a ellas. Separa la documentación en secciones y temas de manera lógica.

Cada sección o tema debe abordar una sola cuestión, ya sea una sola característica o tarea del programa. Los temas relacionados pueden abordarse utilizando listados de “véase también” o hipervínculos, en la medida que sea necesario.

Para crear tu documentación de software vas a necesitar un programa para la escritura y una herramienta para realizar capturas de pantallas.

Referencia

http://www.softwaredocumentation.info/DocumentingSoftware.aspx

http://www.techscribe.co.uk/ta/how-to-write-user-documentation.htm

 

Leave a Reply