Cómo escribir buena documentación (una guía de paso por paso)

Su vida puede ser mucho más fácil una vez que sepa cómo escribir documentación: documentación buena y útil, que en realidad ofrece a sus usuarios lo que necesitan. Después de todo, todos leen la documentación:
Los equipos de marketing funcionan con libros de texto, una especie de documentación de marketing.
Los equipos técnicos y de asistencia utilizan guías de uso, libros de texto de instalación, notas de código: documentación técnica “básica”.
Otros se basan en procedimientos operativos estándar, materiales de referencia, documentos de proceso, listas de verificación: documentación típica del conocimiento de la empresa.
Los clientes también usan la documentación para que los clientes aprendan a resolver una solución o para solucionar problemas de sus problemas (asistencia de nivel 0).
Aunque no hay una forma estándar de crear toda esta documentación, los pasos fundamentales siguen siendo los mismos. Pero antes de verlos, echemos un vistazo rápido a los diferentes tipos de documentación. Según su propósito, una documentación puede ser uno de los cuatro tipos. Tipos de documentación en su discurso sobre los tipos de documentación, Daniele Procida o Divio AG clasifican la documentación en cuatro tipos:
tutoriales orientados hacia el aprendizaje
Guías orientadas a objetivos
Discusiones orientadas hacia la comprensión
material de referencia orientado hacia la información
Como puede entender por la forma en que lo expresa, cada documentación tiene un objetivo diferente, y los responsables de la documentación deben establecerlo cada vez que pretendan crear uno. Dado esto, comencemos con nuestra guía sobre cómo escribir la documentación.
Determine si realmente tiene que documentar su producto puede hacer cien cosas. Puede haber varias formas de personalizarlo. Podría tener una base de código de miles de líneas. Y también puede generar muchos conocimientos en el trabajo diario. Pero no es posible documentar todo … y no todo debe documentarse. Entonces, antes de responder la pregunta “Cómo escribir la documentación”, sabe si tiene que documentarla en absoluto. Antes de documentarlo, piense en los lectores objetivo. Los lectores objetivo para su documentación podrían ser cualquier persona, desde un usuario final hasta los desarrolladores de software o la persona de recursos humanos. ¿Eres trabajadores de conocimiento? Piense en lo que estas audiencias objetivo están luchando … y si realmente puede alentarlos a hacerlo mejor. Además, piense en cómo lo usarán. Piense en cómo los usuarios específicos interactuarán con su documentación que sus clientes seguirán su paso a paso para comenzar con su solución. Lo que hace que la documentación sea “orientada hacia objetivos”. ¿O sus desarrolladores lo usarán mientras trabajan y colaboran en su próximo ciclo de lanzamiento? En este caso, observa la documentación “orientada hacia la comprensión”. ¿O su recurso de recursos humanos se referirá a ella cuando procese las solicitudes? Tiene una documentación “orientada a la información” aquí.
¿Y su documentación realmente los ayudará? Además, es posible que desee pensar en cómo sus esfuerzos de documentación lo ayudarán en un nivel superior:
¿Su documentación mejorará su soporte de nivel cero y permitirá que sus usuarios finales resuelvan sus propios problemas (desviación)? ¿Los equipos mejorarían en lo que hacen?
¿Su equipo se volverá más productivo?
Descubra cuándo documentarlo, la idea general no es comenzar demasiado temprano (o tarde). A menos que esté seguro sobre cómo tendrá lugar un proceso o cómo realizará su “visión”, es mejor no documentarlo y esperar hasta que las cosas se materialicen un poco.
Por ejemplo, si planea una actualización significativa en el próximo trimestre y el trabajo solo está en la etapa conceptual de alto nivel, todavía no involucra recursos documentales. Este es el enfoque “ágil” de la documentación.
La fuente de la imagen a menudo, el mejor momento para hacer ciertos tipos de documentación (como procedimientos y procesos) es cuando realmente los realiza. Ponga la mejor manera de documentarlo de acuerdo con los tipos de documentación que necesita, necesita uno o más lugares para mantener todo. Funcionan como su fuente única de verdad.
Chastity Blackwell de Yelp comparte algunas de las frustraciones cuando toda su documentación no se almacena maravillosamente en un solo lugar: tiene un documento que explica todo sobre ese servicio y está seguro de que la información que necesita para resolver este incidente está allí, en algún lugar. “Puedes tratar de buscar esto en Wiki o tal vez esté en el almacén de Google Docs. Ah, y tengo algunas notas en mi director de origen y creo que vi un correo electrónico al respecto hace algún tiempo “. Por supuesto, no quieres que eso te suceda. Es por eso que debe elegir cuidadosamente las herramientas de documentación. Si se documenta para los usuarios finales, es mejor usar una solución básica de conocimiento fácil de completar, como la base de conocimiento heroico. Puede encontrar algunas alternativas aquí. Si se documenta para sus equipos, elija una solución de wiki como Wikipress o una solución interna de gestión de conocimiento de la base de conocimiento heroico (¡sí, doble!). O verifique algunas de estas opciones para soluciones de gestión del conocimiento. Finalmente, si documenta el código, es posible que desee considerar algunas de las soluciones de documentación técnica más especializada. Algunas soluciones básicas de uso general, como la base de conocimiento heroico, el trabajo y las soluciones de documentación técnica. Al elegir su sistema documental, asegúrese de elegir uno que sea fácil de actualizar, ¡porque puede descubrir que a menudo actualiza su documentación! Su herramienta documental también debe proporcionar una excelente búsqueda.

Decide qué escribir porque la documentación puede tomar tantas formas, es esencial completar un formato antes de escribirlo. Por ejemplo, en Herotemes, usamos una combinación de preguntas frecuentes, tutoriales de instalación, guías de solución de problemas, consejos y trucos. Y otros. Para nuestra documentación dirigida a los clientes. La mayoría de nuestros clientes también usan una composición similar. Dependiendo de la documentación que produzca y para quién, necesitará saber qué formularios su documentación de Jacob Kaplan-Moss puede tomar en detalle sobre qué escribir. Explica cómo los tutoriales, las guías temáticas y los materiales de referencia son la mayoría de la documentación en la mayoría de los casos:
Tutoriales: los tutoriales o instrucciones son la forma más básica de documentación. Para nuestra documentación dirigida a los clientes, los tutoriales son nuestros recursos de uso que nuestros usuarios utilizan para agregar una base de conocimiento a su sitio web con nuestro complemento o para completarlo con artículos.
Guías de sujetos: las guías sujetas tienden a ir mucho más profundas que los tutoriales y se dirigen a temas más especializados. Para nosotros, estas son nuestras guías sobre temas como la traducción e integración. Los clasificamos vagamente como temas avanzados.
Referencia: en el contexto de nuestra documentación dirigida a los clientes, este tipo contiene información sobre nuestras integraciones con nuestros socios que nuestros usuarios podrían encontrar útiles al configurar sus integraciones. O enlaces a cualquier cosa que puedan encontrar útiles cuando se implementen cualquiera de nuestras soluciones de Herotemia.

Comience con un archivo ReadMe (y construya en él), sin embargo, ahora está listo para el lado escrito. La parte de escritura de documentación comienza con un archivo ReadMe. Piense en ello como en la portada o esbozó su documentación. Si trabaja en su documentación de código que sus colegas utilizarán (desarrollador/probador/optimizador), el archivo ReadMe se verá de cierta manera.
La fuente de la imagen y si escribe documentación orientada al cliente, es posible que desee adaptarla para tener sentido para el público objetivo y el trabajo a realizar. El contenido, sin embargo, sigue siendo más o menos igual. A continuación, puede ver cómo un elemento de asistencia explica cómo comienza una integración con una portada.
La fuente de la imagen ahora, tome el archivo ReadMe o el bosquejo de documentación y complete una sección. Aquí hay algunos recursos en nuestro blog para ayudarlo a completar su documentación:
La plantilla del artículo de la base de conocimiento definitiva (infografía): hemos investigado los artículos más exitosos en la base de conocimiento de nuestros clientes y decodificamos lo que parece un buen artículo de la base de conocimiento. Dichos artículos son una parte importante de la documentación orientada a sus usuarios, así que use esta infografía para crearlos a una velocidad récord.
Cómo escribir procedimientos operativos estándar (SOP), paso a paso: esta es una forma rápida de escribir algunas instrucciones o procedimientos de operación estándar que ofrecen instrucciones paso a paso cómo completar el trabajo estipulado, muy útil al crear un wiki interno de la empresa o una base de conocimiento.
¿Cuál es la documentación del proceso?Y cómo documentar sus procesos correctamente: otra forma rápida de escribir la documentación del proceso, una parte esencial de la combinación de conocimiento interno de la compañía. Cómo escribir preguntas frecuentes y 5 formas simples de escribir las respuestas perfectas a las preguntas frecuentes: estas dos publicaciones ayudarán Prepara sus preguntas frecuentes en una hora y desvía muchas preguntas antes de vender como jefe.

Una vez terminado, no olvide agregar una parte de la revisión y la prueba. La revisión es una parte esencial del proceso de documentación. Ayuda a asegurarte de que tu documentación funcione de manera efectiva. En su proceso de revisión de la documentación de cinco pasos, el escritor técnico Tom Johnson dice que la primera etapa es no estar relacionada en la que usted, el escritor de la documentación, haga que el “producto funcione” para usted después de los pasos que escribió. Establezca un programa de actualización La documentación comienza a aprender tan pronto como se publique. Entonces necesita un programa de actualización. Su frecuencia de actualización dependerá de la documentación que esté buscando. Por ejemplo, su documentación orientada al usuario solo necesitará actualizaciones cuando actualice el producto. La documentación orientada a los desarrolladores, la documentación del código técnico, está en marcha permanentemente (documentación en línea). La documentación de conocimiento/trabajo interno, por otro lado, podría usar la actualización cada vez que cambia algo, por ejemplo, cuando reemplaza la herramienta de gestión de proyectos actual o incluso cuando simplemente descubre una forma más optimizada de trabajar. Capturar el conocimiento tribal y capturar el conocimiento general son algunos de los ejercicios en progreso en dicha documentación. Cuando tenga sentido, mantenga los cambios en los cambios en su documentación para que los usuarios no se sientan perdidos cuando ven una versión actualizada. Además, como parte de la actualización de documentación, elimine los archivos obsoletos y duplicados. Una búsqueda en su documentación.