10 consejos para crear documentación de calidad y eficaz

Este artículo de blog también está disponible en formato PDF en la biblioteca de descargas de Newsmatic.

Seamos honestos. Nadie quiere escribir sobre ello, leer sobre ello o tener que hacerlo realmente. Estoy hablando de la documentación, generalmente definida como el penúltimo paso en el ciclo de vida del proyecto. Aunque la documentación puede y debe ocurrir en cualquier momento del ciclo de vida del proyecto, me centraré en esta fase en particular. Tenga en cuenta que hay dos subconjuntos de documentación de los que hablaré, documentación para el usuario final y documentación interna/sistema.

El ciclo de vida del proyecto

Mientras investigaba para este artículo, consulté la Enciclopedia de Ciencias de la Computación, editada por Anthony Ralston y Chester L. Meek, Petrocelli/Charter, 1976. Es definitivamente un clásico de primera edición, pero algunas cosas son atemporales. Dice en el apartado sobre documentación:

"La documentación es una parte vital del desarrollo y uso de un sistema basado en computadora. En algunas organizaciones comerciales, del 20 al 40% del esfuerzo total de desarrollo se destina a la documentación del nuevo sistema, que registra cómo funcionará el nuevo sistema y cómo se desarrolló". Autor, K.R. London

Tenía curiosidad por saber si eso todavía es cierto hoy en día y, de ser así, por qué la documentación no recibe la cobertura mediática que se merece. No pude encontrar mucha información sobre los costos de la documentación durante el ciclo de vida del proyecto. (ver Figura A). Sospecho que estos costos a menudo se subestiman o no se recopilan adecuadamente. Para los profesionales de TI cuyo trabajo es desarrollar sistemas funcionales, muchos pueden considerar admitir los costos reales de la documentación como embarazoso o que refleja negativamente en su productividad y trabajo.

Su opinión sobre la fase de documentación del ciclo de vida del proyecto probablemente depende de su rol en la organización de TI. Si es un gerente o un líder de proyecto, la documentación es fundamental para el éxito del proyecto. Si se encuentra en una posición no gerencial, la documentación es una molestia molesta que se interpone en su trabajo real. Si bien los 10 consejos a continuación están dirigidos principalmente a esta última categoría, los gerentes y supervisores también pueden beneficiarse de ellos.

10 pasos para reinstalar Windows y optimizar su rendimiento

Figura A

Fuente de los siete pasos del ciclo de vida del proyecto: WikipediA

#1: Documenta con imágenes si es posible

El viejo dicho "una imagen vale más que mil palabras" significa que al usar imágenes para complementar tu texto, puedes minimizar la longitud y complejidad de tu documentación. A los usuarios les gusta tener imágenes, diagramas, tablas y listas con viñetas para consultas rápidas.

#2: Proporciona ejemplos

Los ejemplos son una excelente manera para que los usuarios finales comprendan rápidamente conceptos que quizás no entiendan completamente. También es una buena forma para que un usuario final que está aprendiendo un nuevo software pueda enfrentar un nuevo desafío más fácilmente. Aquí tienes un ejemplo de documentación con imágenes:

Versiones anteriores en Vista Business, Ultimate y Enterprise

Versiones Anteriores es el término que Microsoft utiliza para guardar copias sombra de un archivo. Si estás trabajando en un documento u otro proyecto que requiere mucho trabajo y has perdido accidentalmente parte o todo tu trabajo, puedes volver a una versión anterior. Piénsalo como una forma automatizada de tomar instantáneas de cómo se veía el archivo en puntos de tiempo anteriores.

Pero primero tendrás que configurar Vista para que las Versiones Anteriores (Figuras B a E) estén activadas para las unidades/particiones lógicas para las que deseas habilitar la capacidad de restaurar las versiones anteriores de tus archivos.

Activar las Versiones Anteriores

Cómo administrar relaciones de confianza en Active Directory

Figura B

Selecciona Inicio | Panel de control

Figura C

Haz clic izquierdo en Configuración avanzada del sistema — Haz clic izquierdo en Continuar si te lo solicita el Control de cuentas de usuario (UAC)

Figura D

Haz clic izquierdo en la pestaña Protección del sistema

NOTA: La unidad/partición lógica de Vista ya está habilitada de forma predeterminada. Cambia esta configuración solo si comprendes completamente las consecuencias de hacerlo.

Figura E

Desplázate hacia abajo y selecciona la unidad lógica

Haz clic izquierdo en la barra de desplazamiento y desplázate hacia abajo a través de las unidades/particiones lógicas hasta encontrar aquella en la que deseas habilitar Versiones Anteriores. En este ejemplo, el nombre de la unidad lógica es Documentos. Haz clic en la casilla de verificación junto al nombre de la unidad lógica.

Cómo personalizar el color de los símbolos en una lista con viñetas en Word

NOTA: Las copias sombra se crean en función del tiempo y la frecuencia de los puntos de restauración creados por el sistema. Según el archivo de ayuda de Vista, esto ocurre generalmente una vez al día.

Haz clic en Aplicar y luego haz clic en Aceptar para cerrar la ventana Propiedades del sistema. Haz clic en Archivo | Cerrar o haz clic en la X roja en la parte superior derecha de la ventana Panel de control | Sistema para cerrarla.

Para restaurar la versión anterior de un archivo, puedes hacer clic derecho en el nombre del archivo en el Explorador y seleccionar Restaurar versiones anteriores.

NOTA: Una vez que se haya restaurado una copia sombra de un archivo, ya no estará disponible para una segunda restauración. No se creará otra copia sombra hasta que se cree el siguiente punto de restauración del sistema. Esto significa que cualquier archivo guardado antes del siguiente punto de restauración no se puede restaurar a la misma versión anterior que habías usado anteriormente. Se debe tener precaución al guardar archivos después de usar la opción Restaurar versiones anteriores hasta que se cree el siguiente punto de restauración y se pueda crear otra copia sombra.

#3: No des nada por sentado

Incluso si conoces tu público objetivo, tu documentación debe estar escrita de manera que cualquier persona con conocimientos básicos de informática pueda leerla y aprender a utilizar correctamente el sistema. Debes proporcionar instrucciones paso a paso cuando sea posible, pero considera colocarlas en un apéndice, un capítulo separado o hacerlas disponibles mediante un hipervínculo para evitar el desorden. Si estás haciendo la documentación, cambia tu forma de pensar para ponerte en el lugar de un nuevo usuario del sistema. Eso puede ser difícil al principio, pero si prestas atención a los detalles y documentas todas las funciones y características, puedes crear documentación que no asuma que el usuario puede averiguar la información y los procedimientos que has olvidado incluir.

No asumas que tu usuario final entiende todos los acrónimos que inundan el paisaje de TI. La primera vez que presentes un nuevo acrónimo, explica qué significa.

Cómo hacer que el contenido de tu documento de Word se ajuste a una sola página

#4: Anticipa problemas

Cuando pruebes tu sistema, deberías haber intentado romper el software de todas las formas posibles. Si tu software tiene problemas conocidos (a los desarrolladores les gusta llamarlos problemas; los usuarios finales los llaman errores), documenta una solución alternativa y proporciónala a tus usuarios y al servicio de asistencia. No solo ahorrarás mucha frustración para los usuarios finales, sino también muchas llamadas adicionales al servicio de asistencia.

Documenta los eventos que son inevitables durante la vida útil de cualquier sistema a largo plazo:

• ¿Qué soluciones alternativas están disponibles mientras el sistema o la red están fuera de servicio?
• ¿Cómo se recupera de una interrupción del servidor, un fallo del disco duro o una corrupción de la base de datos?
• ¿Cómo puede alguien que no sabe absolutamente nada sobre tu sistema volver a ponerlo en funcionamiento?

Tu documentación debe anticipar estos problemas y proporcionar un plan detallado e instrucciones para la recuperación del sistema.

¿La persona que te reemplaza sabrá dónde encontrar tu documentación y cualquier documentación de la aplicación del proveedor que hayas adquirido? Todos estos documentos deben estar organizados y almacenados de forma ordenada en un lugar seguro y conocido.

Otro buen ejemplo de anticipación de problemas es el problema y la solución del Efecto del Milenio del año 2000. Los medios de comunicación comenzaron a informar a fines de la década de 1990 que los sistemas y software podrían fallar debido al almacenamiento de solo dos dígitos para el año en los sistemas heredados. Este problema se anticipó por adelantado y se hizo un gran esfuerzo para solucionarlo antes de que ocurriera. El software en desarrollo se construyó y certificó como compatible con el Efecto del Milenio años antes del 1 de enero de 2000. Los resultados fueron notablemente exitosos. A excepción de algunos problemas menores reportados, el Día de Año Nuevo de 2000 fue una ocasión festiva y no un desastre para la comunidad de TI, aunque muchos de nosotros estábamos de guardia por si acaso.

La misma mentalidad se puede utilizar para anticipar problemas que podrían surgir en tu documentación. El problema del Efecto del Milenio también ilustra la necesidad de actualizar continuamente los documentos. La Documentación Interna/Sistema se modificó para señalar la compatibilidad o no con el Efecto del Milenio del software y los sistemas. Para los sistemas heredados más antiguos, se encontraron soluciones alternativas y se documentaron.

Cómo cambiar el tipo y tamaño de fuente en Outlook: Guía paso a paso

#5: Prueba tu documentación

Siéntate y sigue tus propias instrucciones. Si estás documentando la construcción de un servidor, una red o cualquier otro sistema de TI, comienza con una partición limpia y construye todo desde cero. Sin duda, descubrirás que has olvidado algo o que algunas de tus instrucciones no son claras.

Trabaja con un compañero de trabajo informado pero sin conocimientos del tema para obtener comentarios antes de publicar. Permítele probar tu documentación.

Te sorprenderá lo que aprenderás cuando sientes a una persona a trabajar con tu software y documentación por primera vez. Muchas características del software que son obvias para ti no lo serán tanto para alguien que es honesto y está dispuesto a trabajar contigo. Observa atentamente lo que hace tu conejillo de indias mientras navega por tu software. Pide comentarios y toma notas.

Recuerdo los comentarios que recibí durante las pruebas de uno de mis proyectos. Los comentarios estaban escritos en un correo electrónico para que pudiera revisarlos punto por punto. La primera idea que me vino a la mente fue "¿cuánto tiempo llevará hacer esto?" También puedes tomar estos comentarios como algo crítico o personal. No cometas ese error. Mirando hacia atrás, debería haber implementado más de las características faltantes que mi crítico amable había proporcionado.

Aprovecha esta oportunidad para hacer los ajustes finales a tu proyecto. Los comentarios durante el proceso de documentación pueden ayudarte a hacer que el proyecto en general sea más exitoso.

Estaba escribiendo una reseña para la placa madre Foxconn 975X7AB-8EKRS2H y encontré dos errores en el manual. No fui la primera persona en revisar la placa. Foxconn pasó por alto los errores y todos los demás revisores también lo hicieron. Un error en el manual estaba lejos de ser trivial.

Cómo instalar APFS para Windows: una solución para la compatibilidad de sistemas operativos

El diagrama en el manual que muestra la posición normal de la configuración del jumper de clear CMOS era incorrecto. Lo sé porque cuando giré la placa madre para verificar la correcta colocación del disipador de calor, el jumper se cayó. Volví a colocar el jumper según las instrucciones en el manual. La computadora no se inició correctamente. Después de examinar cuidadosamente el diminuto diagrama en la placa madre, descubrí el error y corregí la ubicación incorrecta del jumper.

En ese momento estaba trabajando con un técnico de Foxconn que fue lo suficientemente amable como para responder mis preguntas y le informé sobre el error. Es fácil pasar por alto errores como este en la documentación y pueden generar costos potencialmente grandes para el fabricante. Yo también habría pasado por alto el error si el jumper no hubiera estado lo suficientemente suelto como para caerse cuando giré la placa madre.

#6: Humaniza tu trabajo

¿Cuántas veces has leído un manual de usuario y te has preguntado si realmente hay un ser humano en el otro extremo de la creación del manual, o fue una computadora la que hizo ese manual? Aunque no quieres crear una novela colorida, humaniza el documento lo suficiente con algo de tu personalidad para que el lector se sienta un poco más cómodo al leerlo.

#7: Explora nuevas tecnologías

La documentación puede ser costosa incluso cuando se hace correctamente. Se seguirán creando nuevas tecnologías para ayudar a crear documentación más efectiva que sea menos costosa de desarrollar. Mira estas nuevas herramientas como oportunidades para reducir el tiempo y el costo del proceso de documentación.

Documentar como parte de un equipo de proyecto puede ser especialmente difícil. Tu documentación debe compartirse y agregarse a la documentación de otros miembros del equipo. Los cambios deben realizarse, a menudo, a diario. Existen software que permiten esto y no solo ayudarán a garantizar un producto final estandarizado, sino que también ayudarán a fomentar el intercambio de ideas y conocimientos entre los miembros del equipo.

Cuando trabajaba en CSC (Computer Sciences Corporation), experimenté con el Agente de Microsoft y la tecnología de texto a voz con resultados mixtos. Siempre pensé que ofrecía formas maravillosas de guiar a un nuevo usuario a través de algunas de las características de mi sistema. Algunos pueden recordar ese pequeño personaje de clip de papel ofensivo con los ojos parpadeantes en Word 97. Fue un poco más que molesto.

Cómo aplicar formato condicional en Excel para dividir grupos

Con el Agente, puedes hacer que tu personaje se mueva por la pantalla, señale una casilla desplegable, abra programáticamente la casilla desplegable y permita que el personaje te hable sobre las opciones presentadas. Creé un recorrido guiado de mi software y dejé que Peedy, el loro, señalara las casillas, llenara cajas de texto, cambiara pantallas y guiara al usuario final a través de todo el proceso de creación de un nuevo registro en la base de datos.

Descubrí que utilizar el Agente me ahorró tener que escribir muchas páginas tediosas de documentación que detallaran los pasos necesarios para crear, guardar y modificar nuevos registros. También fue divertido de desarrollar. Permitió que mi lado creativo participara de una manera positiva y beneficiosa. La creatividad está programada en la mayoría de los desarrolladores y es un componente clave de lo que los hace exitosos. La creatividad se puede y se debe considerar al desarrollar tu documentación, según las normas y expectativas de tu empresa.

La única respuesta que recibí sobre mi experimento con MS Agent fue que alguien tenía demasiado tiempo libre y que no se lo tomó en serio, al menos en parte debido al aspecto cómico del personaje. No fue mucho trabajo adicional construirlo, pero sí me requirió aprender algunas técnicas de programación nuevas. Fue un placer cuando alguien de nuestro departamento tenía que ser capacitado. Le dije que hiciera el recorrido guiado. Tal vez Microsoft estaba adelantado a su tiempo, y con un personaje más respetable, este tipo de tecnología todavía podría convertirse en algo común algún día.

Recientemente construí una computadora para mi padre como regalo de aniversario de bodas número 50. Documenté algunas notas tituladas Notas Importantes de la PC, POR FAVOR Leer y dejé un acceso directo en el escritorio. También creé un archivo de audio que documentaba las características y el uso de la computadora. Tuve que preguntarle si había leído mis notas, pero se ofreció a decirme que había hecho el recorrido de audio de la computadora.

Estos son solo algunos ejemplos de formas alternativas de documentar. En mi humilde opinión, las nuevas formas de documentar se subutilizan y se subestiman por su simplicidad e impacto potencial en el entorno corporativo actual.

Aún no se ha desarrollado el paquete de software de documentación que lo resuelva todo, pero hay varias herramientas de documentación útiles diseñadas para tareas de documentación específicas.

Cómo acceder y configurar el firewall de Windows Defender en Windows 10

#8: Haz la documentación tú mismo si es posible

La mejor persona para documentar es el creador. Después de todo, ¿quién conoce el sistema mejor que el creador del sistema?

Si eres el creador del sistema, es probable que seas un programador excelente. Pero menciona la palabra documentación a un programador y te dará una mirada de "debes estar bromeando". Si se les obliga, los programadores documentarán su trabajo, o al menos intentarán crear algo que pueda pasar como documentación. Lo sé. Lo he visto con demasiada frecuencia e incluso lo he hecho yo mismo.

Y eso es una verdadera lástima porque un programador con buenas habilidades de documentación es un activo valioso para la empresa. ¿Qué recordará tu gerente cuando llegue el momento de la revisión de rendimiento si otra persona tuvo que hacer la documentación de tu proyecto? Mi suposición es que no será que merezcas un ascenso, un aumento de sueldo o un bono.

Aunque no es exactamente divertido, la documentación puede ser gratificante cuando se hace correctamente. No solo tendrás un proyecto general mejor para presentar a tu cliente, sino que también reducirás en gran medida el tiempo de soporte futuro que tendrás que proporcionar. También puedes reducir la cantidad de tiempo de soporte y mantenimiento para el servicio de asistencia.

Cuando trabajaba en CSC, tuve la oportunidad de ser el líder del proyecto para el diseño y la creación de nuestro sistema de informes y la infraestructura global. Pude ver de primera mano el otro lado de la documentación. Teníamos un programador muy bueno en el grupo que trabajaba con la API de Crystal Reports y la creación de funciones personalizadas. Era obvio para mí que su conocimiento era único y tenía que ser compartido con el resto del equipo, ¿y qué mejor manera de hacerlo que documentar adecuadamente su trabajo? No tuve un éxito total en hacer que explicara su trabajo hasta el punto en que otra persona pudiera hacerse cargo y continuar. Sin embargo, enumeró y explicó los nombres de las funciones, cómo usarlas, cómo funcionaban y qué lograban, y eso fue de gran ayuda para los demás miembros del equipo.

Parece haber una regla no escrita en el Reino del Código de que las habilidades de programación son inversamente proporcionales a la cantidad de documentación que los programadores tienen que hacer.

SQL Server 2022: Mejoras en seguridad y rendimiento con enfoque en la nube de Azure

El segundo elogio más importante que se me ha hecho en mi carrera fue cuando tuve que hacer una presentación a nuestro equipo global de soporte técnico. Tuve que crear y presentar documentación sobre cómo construir un servidor de informes. Uno de nuestros administradores de bases de datos era un tipo de Inglaterra que tuvo que estar presente en la presentación. Miró el documento Cómo construir un servidor de informes y, parafraseando, comentó lo buena que era la documentación y que debería poder construir un servidor de informes utilizando mi documentación. Elogios como ese hacen que todo el arduo trabajo valga la pena. Y no fue un elogio por el trabajo principal del proyecto, sino por la documentación.

#9: Coordina el desarrollo de la documentación para el usuario final con la documentación interna/sistema

Puedes reducir el tiempo de documentación si construyes tu documentación para usuarios finales al mismo tiempo que escribes la documentación del sistema. Puedes compartir parte de la información entre las dos y reducir la falta de información. Incluso si no quieres o no es apropiado compartir información entre los documentos, puedes beneficiarte de los temas en un documento que te recuerden incluir documentación adicional en el otro.

#10: Sigue las pautas de documentación del departamento o de la empresa

Crea y sigue formatos y pautas estándar. Esto ayudará a garantizar que no se excluya información importante y permitirá una lectura más fácil para los usuarios del sistema.

La única vez que tuve un experto en documentación dedicado trabajando conmigo para documentar mi sistema fue en Hughes Aircraft Company. Los resultados fueron excelentes. El formato era el estándar del departamento y los resultados fueron mejores de lo que yo hubiera hecho. Se requirió mucho tiempo y esfuerzo para obtener esos resultados. El experto en documentación necesitaba acceso a mi sistema beta y acceso a mí para que pudiera hacer preguntas. Esto es más caro y no todas las empresas tienen los recursos para asignar a la documentación profesional, pero los resultados pueden ser excelentes si el creador del sistema puede verificar que la información importante no se interpreta de manera incorrecta ni se excluye del producto final.

Tuve la suerte de contar con un ex ingeniero que también era excelente para escribir documentación. Entendía para qué estaba diseñado y construido mi sistema y completaba los vacíos utilizando el sistema y descubriendo por sí mismo cómo funcionaba. Es posible que no tengas tanta suerte.

En esta era de marketing, ventas y soporte global, la documentación también debe seguir los estándares del país o de la región. A menudo me molesta leer el manual de un aparato electrónico fabricado en China que, con demasiada frecuencia, es difícil de traducir. Está escrito en un chinglish y para algunas oraciones tengo que detenerme y tratar de comprender. Generalmente simplemente hago un sonido mental al estilo de Scooby Doo y sigo con el resto del manual.

Cómo agregar acceso al Panel de Control en el Explorador de Archivos de Windows 11

Si los profesionales de la documentación que hablan inglés aprendieran (nunca lo hacen) y escribieran en chino, imagino que su Englese sonaría igual para las personas que hablan chino. Busca y utiliza un traductor profesional para que la documentación sea comprensible y no se pierda información importante en la traducción.

También debería mencionar lo obvio. Tu documentación debe estar libre de errores ortográficos y gramaticales. Siempre utiliza un corrector ortográfico para encontrar errores. Nunca dejo de sorprenderme de cuántos errores ortográficos evidentes he cometido y simplemente he pasado por alto en una relectura.

Desarrollador de documentación

Si aún no he logrado convencerte de que crear una buena documentación es bueno para ti y para tu empleador, tómalo como un hecho: crear una buena documentación no es solo una tarea insignificante. Cuando documentas tu trabajo, también te conviertes en un desarrollador de documentación. Espero que estos consejos te ayuden a evitar esas preguntas que consumen tiempo y que seguramente te harán tus compañeros o el amigable personal del servicio de asistencia.

Nota del autor:

Este es mi primer documento oficialmente publicado. Deseo agradecer personalmente a Sonja Thompson y Mark Kaelin por darme esta oportunidad de compartir mis ideas con ustedes. No estoy seguro de por qué Mark decidió ofrecerme la oportunidad de discutir un tema tan exigente como la documentación para mi primer artículo. ¡Quizás pensó que si podía escribir un artículo interesante sobre documentación, podría escribir sobre casi cualquier cosa! Estoy contento de que lo haya hecho y mi agradecimiento hacia él y Newsmatic es más de lo que puedo expresar con las herramientas de este oficio.

Un amable lector se ha convertido en un amable escritor.

Referencias adicionales:

• "...los cuatro atributos más importantes sobre la documentación incluyen su contenido, mantenimiento, disponibilidad y uso de ejemplos". Página 58 de http://www.site.uottawa.ca/~tcl/gradtheses/aforward/aforward_thesis.doc
• La importancia de la documentación: http://searchsmb.techtarget.com/originalContent/0,289142,sid44_gci1251087,00.html

En Newsmatic nos especializamos en tecnología de vanguardia, contamos con los artículos mas novedosos sobre Microsoft, allí encontraras muchos artículos similares a 10 consejos para crear documentación de calidad y eficaz , tenemos lo ultimo en tecnología 2023.