Cómo escribir documentación de software

Descargar el PDF
Descargar el PDF

Una buena documentación de software, ya sea un documento de especificaciones para programadores y ensayadores, un documento técnico para usuarios internos, o manuales de software y documentos de ayuda para usuarios finales, ayuda a que la persona que trabaja con el software entienda sus características y funciones. Una buena documentación de usuario es específica, concisa, y relevante, y le brinda toda la información importante a la persona que utiliza el software. A continuación se presentan instrucciones de cómo escribir una documentación de software para usuarios técnicos y usuarios finales.

Método 1
Método 1 de 2:

Escribe una documentación de software para usuarios técnicos

Descargar el PDF
  1. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-460px-Write-Software-Documentation-Step-1.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-728px-Write-Software-Documentation-Step-1.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Los documentos de especificaciones de software sirven como manuales de consulta para los diseñadores de la interfaz de usuario, los programadores que escriben el código, y los ensayadores que verifican que el software funcione como es debido. La información exacta depende del programa en cuestión, pero puede incluir cualquiera de las siguientes cosas:
    • Archivos esenciales dentro de la aplicación. Esto puede incluir los archivos creados por el equipo de desarrolladores, 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.
  2. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-460px-Write-Software-Documentation-Step-2.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-728px-Write-Software-Documentation-Step-2.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Cuanto más desarrolles la documentación técnica dentro del código fuente del programa, más fácil será actualizarla y mantenerla a la par del código, y también será más fácil documentar las diversas 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.
    • Si el código fuente es especialmente 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 especialmente 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 ciertas aplicaciones de internet.
    • Algunos lenguajes de programación, como Java y la infraestructura digital (framework) .NET (Visual Basic.NET, C #), 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.
  3. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-460px-Write-Software-Documentation-Step-3.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-728px-Write-Software-Documentation-Step-3.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    Hasta cierto punto, esto está determinado por el 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.
    • Los procesadores de texto de Microsoft Word son adecuados 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.
    Anuncio
Método 2
Método 2 de 2:

Escribe documentación de software para usuarios finales

Descargar el PDF
  1. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-460px-Write-Software-Documentation-Step-4.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-728px-Write-Software-Documentation-Step-4.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  2. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-460px-Write-Software-Documentation-Step-5.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-728px-Write-Software-Documentation-Step-5.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  3. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-460px-Write-Software-Documentation-Step-6.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-728px-Write-Software-Documentation-Step-6.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  4. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-460px-Write-Software-Documentation-Step-7.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-728px-Write-Software-Documentation-Step-7.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  5. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-460px-Write-Software-Documentation-Step-8.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-728px-Write-Software-Documentation-Step-8.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
    Anuncio

Consejos

  • El texto debería 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.
  • Cualquiera de las herramientas de documentación mencionadas antes pueden complementarse con un programa que permita tomar capturas de pantalla, como Snagit, si la documentación requiere algunas capturas de pantalla. Al igual que con otras documentaciones, las capturas deben incluirse para ayudar a explicar cómo funciona el programa, no para deslumbrar al usuario.
  • El tono es particularmente importante, especialmente cuando se escribe documentación de software para usuarios finales. Nombra al usuario utilizando la segunda persona “tú” en vez de utilizar la tercera persona “los usuarios”.
Anuncio

Cosas que necesitarás

  • Programas para crear documentaciones o archivos de ayuda
  • Herramienta para tomar capturas de pantalla

wikiHows relacionados

Cómo
tomar una captura de pantalla en una Dell
6 maneras de evitar que Teams cambie tu estado a Ausente
Cómo
convertir binario a decimal
Cómo
ejecutar un archivo jar java
Cómo
abrir archivos EPUB
Cómo
abrir un torrent
Cómo
abrir archivos BIN
Cómo
activar AutoCAD
Cómo
crackear un programa modificando los archivos DLL
Cómo
usar DOSBox
Cómo restablecer la contraseña de un router Huawei
Cómo
aumentar las semillas en Utorrent
Anuncio

Referencias

  1. http://www.softwaredocumentation.info/DocumentingSoftware.aspx
  2. http://www.techscribe.co.uk/ta/how-to-write-user-documentation.htm
  3. http://www.techscribe.co.uk/ta/how-to-write-instructions.htm
  4. http://www.bluemangolearning.com/blog/2010/05/who-should-write-your-software-documentation-not-tech-pubs/
  5. Rodney Ruff, Omaha, NE; experience as technical writer/help file author since 1997

Acerca de este wikiHow

En otros idiomas
Esta página ha recibido 68 672 visitas.

¿Te ayudó este artículo?

Anuncio