Una buena documentación de software, ya sea documentación de especificaciones para programadores y probadores, documentos técnicos para usuarios internos o manuales y archivos de ayuda para usuarios finales, ayudará a los usuarios a comprender las características y funciones del software. Una buena documentación es documentación específica, clara y relevante, con toda la información que el usuario necesita. Este artículo lo guiará en la redacción de documentación de software para usuarios técnicos y usuarios finales.
Paso
Método 1 de 2: Redacción de documentación de software para usuarios técnicos
Paso 1. Sepa qué información incluir
El documento de especificación se utiliza como manual de referencia para diseñadores de interfaces, programadores que escriben código y probadores que verifican el rendimiento del software. La información que debe incluirse dependerá del programa que se esté creando, pero puede incluir lo siguiente:
- Archivos importantes en la aplicación, como archivos creados por el equipo de desarrollo, bases de datos a las que se accede mientras se ejecuta el programa y aplicaciones de terceros.
- Funciones y subrutinas, incluida una explicación del uso de la función / subrutina, valores de entrada y salida.
- Programar variables y constantes, y cómo se utilizan.
- Estructura general del programa. Para los programas basados en unidades, es posible que deba describir cada módulo y biblioteca. O, si está escribiendo un manual para un programa basado en la web, es posible que deba explicar qué archivos utiliza cada página.
Paso 2. Decida qué nivel de documentación debe estar presente y separarse del código del programa
Cuanta más documentación técnica se incluya en el código del programa, más fácil será actualizarlo y mantenerlo, así como explicar las diferentes versiones del programa. Como mínimo, la documentación en el código del programa debe incluir el uso de funciones, subrutinas, variables y constantes.
- Si su código fuente es largo, puede escribir documentación en un archivo de ayuda, que luego puede indexarse o buscarse con ciertas palabras clave. Los archivos de documentación separados son útiles si la lógica del programa se divide en varias páginas e incluye archivos de soporte, como una aplicación web.
- Algunos lenguajes de programación (como Java, Visual Basic. NET o C #) tienen sus propios estándares de documentación de código. En tales casos, siga la documentación estándar que debe incluirse en el código fuente.
Paso 3. Seleccione la herramienta de documentación adecuada
En algunos casos, la herramienta de documentación viene determinada por el lenguaje de programación utilizado. Los lenguajes C ++, C #, Visual Basic, Java, PHP y otros tienen sus propias herramientas de documentación. Sin embargo, en caso contrario, las herramientas utilizadas dependerán de la documentación requerida.
- Un procesador de texto como Microsoft Word es adecuado para crear archivos de texto de documentos, siempre que la documentación sea concisa y simple. Para crear documentación extensa con texto complejo, la mayoría de los escritores técnicos eligen una herramienta de documentación especializada, como Adobe FrameMaker.
- Los archivos de ayuda para documentar el código fuente se pueden crear con un programa generador de archivos de soporte, como RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare o HelpLogix.
Método 2 de 2: Redacción de documentación de software para usuarios finales
Paso 1. Conozca las razones comerciales que subyacen a la creación del manual
Si bien la razón principal de la documentación del software es ayudar a los usuarios a comprender cómo usar la aplicación, hay varias otras razones que pueden ser la base de la creación de documentación, como ayudar al departamento de marketing a vender la aplicación, mejorar la imagen de la empresa y reducir el soporte técnico. costos. En algunos casos, se requiere documentación para cumplir con las regulaciones u otros requisitos legales.
Sin embargo, la documentación no es un buen sustituto de una interfaz. Si una aplicación requiere mucha documentación para funcionar, debe diseñarse para que sea más intuitiva
Paso 2. Conozca el público objetivo de la documentación
Generalmente, los usuarios de software tienen conocimientos informáticos limitados más allá de las aplicaciones que utilizan. Hay varias formas de satisfacer sus necesidades de documentación:
- Preste atención al título del usuario del software. Por ejemplo, el administrador del sistema generalmente comprende varias aplicaciones informáticas, mientras que la secretaria solo conoce las aplicaciones que usa para ingresar datos.
- Preste atención a los usuarios de software. Aunque sus puestos son generalmente compatibles con las tareas realizadas, estos puestos pueden tener diferentes cargas de trabajo, dependiendo del lugar de trabajo. Al entrevistar a los usuarios potenciales, puede averiguar si su evaluación del puesto de trabajo es correcta.
- Preste atención a la documentación existente. La documentación y las especificaciones de la funcionalidad del software pueden mostrar lo que los usuarios necesitan saber para poder utilizarlos. Sin embargo, tenga en cuenta que los usuarios pueden no estar interesados en conocer las "entrañas" del programa.
- Sepa lo que se necesita para completar una tarea y lo que se necesita antes de poder completarla.
Paso 3. Determine el formato apropiado para la documentación
La documentación del software se puede organizar en 1 o 2 formatos, a saber, libros de referencia y manuales. A veces, combinar los dos formatos es una buena solución.
- Los formatos de referencia se utilizan para describir todas las funciones del software, como botones, pestañas, campos y cuadros de diálogo, y cómo funcionan. Algunos archivos de ayuda están escritos en este formato, especialmente aquellos que son sensibles al contexto. Cuando el usuario hace clic en Ayuda en una determinada pantalla, el usuario recibirá el tema relevante.
- El formato manual se utiliza para explicar cómo hacer algo con el software. Los manuales están generalmente en formato impreso o PDF, aunque algunas páginas de ayuda también incluyen instrucciones sobre cómo hacer ciertas cosas. (Generalmente, los formatos manuales no son sensibles al contexto, pero pueden estar vinculados desde temas sensibles al contexto). Los manuales tienen generalmente la forma de una guía, con un resumen de las tareas a realizar en una descripción y una guía formateada en pasos.
Paso 4. Decidir el tipo de documentación
La documentación del software para los usuarios puede estar empaquetada en uno o más de los siguientes formatos: manuales impresos, archivos PDF, archivos de ayuda o ayuda en línea. Cada tipo de documentación está diseñado para mostrarle cómo utilizar las funciones del software, ya sea una guía o un tutorial. La documentación en línea y las páginas de ayuda también pueden incluir videos de demostración, texto e imágenes estáticas.
Los archivos de ayuda y soporte en línea deben indexarse y buscarse mediante palabras clave para que los usuarios puedan encontrar rápidamente la información que necesitan. Aunque una aplicación de generación de archivos de ayuda puede crear un índice automáticamente, se recomienda que cree un índice manualmente utilizando las palabras clave que se buscan con más frecuencia
Paso 5. Seleccione la herramienta de documentación adecuada
Se pueden crear manuales impresos o PDF con un programa de procesamiento de texto como Word o un editor de texto avanzado como FrameMaker, dependiendo de la longitud y complejidad del archivo. Los archivos de ayuda se pueden escribir con un programa de creación de archivos de ayuda, como RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix o HelpServer.
Consejos
- El texto de la documentación del programa debe estar estructurado de tal manera que sea fácil de leer. Coloque la imagen lo más cerca posible del texto apropiado. Desglose la documentación por secciones y temas de forma lógica. Cada sección o tema debe describir un problema específico, tanto la tarea como las características del programa. Los problemas relacionados se pueden explicar con enlaces o listas de referencias.
- Cada una de las herramientas de documentación descritas en este artículo se puede complementar con un programa de creación de capturas de pantalla, como SnagIt, si su documentación requiere varias capturas de pantalla. Como cualquier otra documentación, también debe incluir capturas de pantalla para ayudar a explicar cómo funciona la aplicación, en lugar de "atraer" al usuario.
- Prestar atención al estilo es muy importante, especialmente si está escribiendo documentación de software para usuarios finales. Diríjase a los usuarios con el pronombre "usted", en lugar de "usuario".
