Instrucciones de paso a paso gratis 
Si el código fuente es particularmente largo, se puede documentar en forma de un archivo de ayuda, que se puede indexar y buscar con palabras clave. Esta es una ventaja particular para las aplicaciones donde la lógica del programa está fragmentada en muchas páginas y contiene una cantidad de archivos adicionales, como con ciertas aplicaciones web. Algunos lenguajes de programación, como Java y .NET Framework (Visual Basic.NET, C#), tienen sus propios estándares para documentar el código. En estos casos, siga los estándares sobre la cantidad de documentación que debe incluirse en el código fuente. 
Los programas de procesamiento de textos para Microsoft Word son suficientes para crear archivos de texto independientes para la documentación, siempre que la documentación sea bastante breve y sencilla. Para archivos de texto largos y complejos, muchos redactores técnicos prefieren una herramienta de documentación como Adobe FrameMaker. Los archivos de ayuda para documentar el código fuente se pueden generar con cualquier herramienta de creación de ayuda, como RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare o HelpLogix. 
Mira las características que tienen tus usuarios potenciales. Es probable que un administrador de sistemas sea un experto en varias aplicaciones de software, mientras que un empleado de ingreso de datos probablemente solo conozca la aplicación que está utilizando para ingresar datos. Mira a los propios usuarios. Si bien los títulos de trabajo generalmente indican lo que hace la gente, puede haber diferencias significativas en cómo se llenan ciertos puestos dentro de una organización. Al entrevistar a los usuarios potenciales puedes hacerte una idea de si tu impresión de lo que indica su posición es correcta o no. Ver la documentación existente. La documentación de versiones anteriores del software (así como las especificaciones funcionales) proporciona una indicación de lo que el usuario necesita saber para usar el programa. Sin embargo, tenga en cuenta que los usuarios finales no están realmente interesados en cómo funciona el programa, sino en lo que puede hacer por ellos. Determinar las tareas que se deben realizar para completar una asignación y qué tareas se deben realizar antes de que se puedan realizar esas tareas. 
Una guía de referencia está dedicada a explicar las funciones individuales de una aplicación de software (botones, pestañas, campos y cuadro de diálogo) y cómo funcionan. Muchos archivos de ayuda están escritos en este formato, especialmente la ayuda sensible al contexto que muestra un tema relevante cuando un usuario hace clic en el botón Ayuda en una pantalla en particular. Una guía del usuario explica cómo usar el software para realizar una tarea en particular. Los manuales de usuario a menudo tienen formato de guías impresas o PDF, aunque algunos archivos de ayuda contienen temas sobre cómo realizar ciertas tareas. (Estos temas de ayuda generalmente no dependen del contexto, aunque pueden estar vinculados a temas que son.) Las guías de usuario a menudo vienen en forma de tutoriales, con una descripción general de las tareas a realizar en la introducción e instrucciones dadas en pasos numerados. 
Los archivos de ayuda y la ayuda en línea deben indexarse y buscarse con palabras clave, lo que permite a los usuarios encontrar rápidamente la información que necesitan. Si bien los creadores de archivos de ayuda pueden generar índices automáticamente, a menudo es mejor crear el índice manualmente, usando términos que los usuarios generalmente buscarán. 
Redacción de documentación para software
Contenido
Una buena documentación de software, ya sea un documento de especificaciones para programadores y evaluadores, un documento técnico para colegas o manuales de software y archivos de ayuda para usuarios finales, ayuda a la persona que tiene que trabajar con el software a comprender todas sus características y funciones. La buena documentación del software es específica, concisa y relevante, y brinda toda la información importante a la persona que usa el software. A continuación, encontrará instrucciones sobre cómo escribir documentación de software para usuarios técnicos y usuarios finales.
Pasos
Método 1 de 2: escribir documentación de software para usuarios técnicos
1. Decidir qué información incluir. Las especificaciones del software sirven como guías para los diseñadores de la interfaz de usuario, los programadores que escriben el código y los evaluadores que verifican que el software funciona según lo previsto. La información exacta depende del programa en cuestión, pero puede incluir cualquiera de los siguientes:
- Los archivos más importantes dentro de la aplicación. Estos pueden ser archivos creados por el equipo de desarrollo, bases de datos a las que se accede durante la operación del programa y utilidades de terceros.
- Funciones y Subrutinas. Esta es una explicación de lo que hace cada función o subrutina, incluidos todos los valores de entrada y salida.
- Programar variables y constantes, y cómo se utilizan en la aplicación.
- La estructura general del programa. Para una aplicación basada en disco, esto podría ser una descripción de los módulos y bibliotecas individuales del programa, mientras que para una aplicación web, podría describir qué páginas usan qué archivos.
2. Decida qué parte de la documentación se debe incluir en el código del programa y qué parte se debe mantener separada. Cuanta más documentación técnica se haya desarrollado ya dentro del código fuente del programa, más fácil será actualizarlo y mantenerlo junto con el código, así como documentar diferentes versiones de la aplicación original. Como mínimo, la documentación dentro del código fuente debe explicar el propósito de las funciones, subrutinas, variables y constantes.
3. Elija la herramienta de documentación adecuada. En cierta medida, esto viene determinado por el lenguaje en el que está escrito el código (como C++, C#, Visual Basic, Java o PHP), ya que existen herramientas específicas para estos y otros lenguajes. En otros casos, el tipo de documentación requerida determina qué herramienta usar.
Método 2 de 2: escribir documentación de software para usuarios finales
1. Determine las razones comerciales de su documentación. Si bien la razón funcional para documentar el software es ayudar a los usuarios a comprender cómo usar la aplicación, existen otras razones, como ayudar en la comercialización del software, mejorar la imagen corporativa y, lo que es más importante, reducir los costos de soporte técnico. En algunos casos, la documentación es necesaria para cumplir con ciertas regulaciones u otros requisitos legales.
- Sin embargo, de ninguna manera la documentación del software debe ser un sustituto de un diseño deficiente de la interfaz. Si una aplicación requiere páginas de documentación como guía, es mejor cambiar el diseño de la pantalla a algo más intuitivo.
2. Comprenda la audiencia para la que está escribiendo la documentación. En la mayoría de los casos, los usuarios de software tienen poco conocimiento de las computadoras más allá de las tareas que pueden realizar con las aplicaciones que utilizan. Hay varias formas de determinar qué necesitan y cómo su documentación puede satisfacerlas.
3. Determinar el formato correcto para la documentación. La documentación del software se puede estructurar en 1 de 2 formatos: el manual y el manual del usuario. A veces una combinación de ambos formatos es el mejor enfoque.
4. Decidir qué forma debe tomar la documentación. La documentación del software puede tomar muchas formas: manuales, documentos PDF, archivos de ayuda o ayuda en línea. Cada formulario está diseñado para mostrar al usuario el uso de cada una de las funciones del programa, ya sea en forma de guía o tutorial; en el caso de archivos de ayuda y ayuda en línea, puede ser texto, videos de demostración e imágenes.
5. Elija una herramienta de documentación adecuada. Los manuales impresos o en PDF se pueden escribir utilizando un programa de procesamiento de texto como Word o un editor de texto avanzado como FrameMaker, según su extensión y complejidad. Los archivos de ayuda se pueden escribir con una herramienta de creación especial como RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix o HelpServer.
Consejos
- El texto debe estar organizado para que sea fácil de leer, con imágenes lo más cercanas posible al texto al que se refiere. Divida la documentación lógicamente en párrafos, secciones y temas. Cada párrafo o tema debe explicar un solo tema, ya sea una sola función del programa o una tarea. Los problemas relacionados pueden explicarse, cuando corresponda, utilizando listas o hipervínculos "Ver también", como se indicó anteriormente.
- Cualquiera de las herramientas de documentación enumeradas anteriormente se puede complementar con un programa de captura de pantalla, como Snagit, si la documentación requiere algunas capturas de pantalla. Al igual que con otra documentación, se deben incluir capturas de pantalla para ayudar a explicar cómo funciona el software, para no confundir al usuario.
- El tono es muy importante, especialmente cuando se escribe documentación de software para usuarios finales. Diríjase a los usuarios en segunda persona ("usted") en lugar de en tercera persona ("usuario").
Artículos de primera necesidad
- Utilidad de documentación de software/archivo de ayuda
- Utilidad de captura de pantalla
Artículos sobre el tema. "Redacción de documentación para software"
Оцените, пожалуйста статью
Similar
Popular
