¿Cómo escribir Documentación de software?
Escribe documentación de software para usuarios finales
Determina los fines comerciales de tu documentación. Entiende para quién estás escribiendo la documentación. Determina el formato apropiado (o los formatos apropiados) para la documentación. Decide qué forma (o qué formas) debería tomar la documentación. Elige la herramienta de documentación apropiada.
Si bien el motivo funcional 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. En algunos casos, 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. 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. La documentación de software puede estructurarse en uno de dos formatos, el manual de consulta y la guía de usuario. 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).  Por lo general, las guías de usuario vienen en forma de tutoriales, con un resumen de la tarea a realizar en la introducción y las instrucciones presentadas en pasos numerados. 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; en el caso de los archivos de ayuda y de ayuda en línea, estos pueden incluir videos demostrativos además del texto y de las imágenes. Los archivos de ayuda en línea deben estar indexados y permitir las búsquedas por palabras claves para que el usuario pueda encontrar rápidamente la información que busca. Aunque las herramientas para crear los archivos de ayuda pueden generar automáticamente los índices, por lo general es mejor crearlos manualmente, usando los términos que los usuarios probablemente busquen. Los manuales de usuario impresos o en PDF pueden escribirse con un procesador de texto como Word o un editor de texto sofisticado como FrameMaker, dependiendo de su largo y su complejidad. Los archivos de ayuda pueden escribirse utilizando herramientas para crear archivos de ayuda como RoboHelp, Help and Manual, Doc-To-Help, Flare o HelpLogix.
Writing Software Documentation for End Users