TL: ¿DR? Bien aquí:
Aparte de contratar o subcontratar a un redactor técnico, ¿existen estándares/convenciones/prácticas básicas que los redactores técnicos emplean en su oficio y que se puedan aprender para crear documentación de TI adecuada y mantener esa documentación a lo largo del tiempo?
Mientras escribíamos documentación variada tanto para uso interno de TI como para uso externo por parte de nuestros empleados, quedó claro que todos nuestros empleados tienen su propio estilo en lo que respecta a la documentación.
A partir de nuestros documentos de calidad y documentación controlada, TI ha utilizado varias plantillas para SOP, WI y varios formularios utilizados para documentos de calidad de TI. Estos documentos, si bien no son necesariamente tan útiles para las operaciones diarias dentro de TI, ayudan a los empleados y a la empresa con problemas de recursos humanos de TI, cumplimiento, etc. y, por lo general, están bien escritos, bien definidos y siguen al menos las plantillas del departamento de Calidad. y estándares de documentación (como control de versiones, ECN, etc.)
Pero nuestra redacción actual de documentos de TI todavía carece de una verdadera convención/estándar. Algunos usarán herramientas de terceros como ScreenSteps, otros simplemente usan Word y crean un esquema simple como:
- Abierto
app- Haga clic en "Iniciar guerra termonuclear global"
- ...
- Ganancia
La documentación interna de TI es en realidad peor, basado en lo que el empleado o consultor consideró suficiente en ese momento para refrescar sus propios recuerdos o se basó en el editor de su elección (vi, word, excel, powerpoint, servilleta, wiki interno). El problema surge cuando un empleado se va o está de vacaciones y se lucha por obtener incluso información básica. A veces, sólo la fecha del expediente es un indicador de si los datos siguen siendo relevantes o no.
Si bien un esquema simple, capturas de pantalla reales o incluso video completo en HD están muy bien, no contamos con un redactor técnico de TI en nuestro personal y no podemos evitar pensar que nos falta algo en esta área.
¿Podríamos crear nuestros propios estándares para nuestra documentación junto con plantillas aprobadas? Sí, pero ¿por qué reinventar la rueda? Si tales estándares y convenciones ya existen dentro del "gremio" de redactores técnicos, sería mejor que siguiéramos esas convenciones para que nuestra documentación sea clara, concisa y profesional.
Para evitar que le digan"Buscalo en Google", Miré sitios que mostraban algunas prácticas de formato y mientras esta SF Q:Plataformas de documentación de TIayuda a encontrar plataformas y software para manejar la escritura, no analiza si realmente existen estándares dentro de la industria.
Entonces, aparte de contratar o subcontratar a un redactor técnico, ¿existen estándares/convenciones/prácticas básicas que los redactores técnicos emplean en su oficio y que se puedan aprender para crear documentación de TI adecuada y mantener esa documentación a lo largo del tiempo?
Respuesta1
Escribir es una disciplina.
he hecho mucho de eso, y tengo todos los conceptos básicos que una persona no capacitada puede obtener sin que la documentación sea una parte importante de mi trabajo. El tiempo me ha mostrado qué documentación que produzco se leerá realmente y qué se guardará en el Estante de Eternal TL;DR. De hecho, esta es la regla número uno para escribir cualquier cosa:
Conozca a su audiencia.
El destinatario de la documentación interna de TI somos nosotros mismos. ¿Y los administradores de sistemas? Cuando buscamos documentación, especialmente documentación interna, buscamos:
- Localizable
- Breve
- Al punto
- Me lleva a donde voy
La explicación de cinco párrafos sobre los antecedentes de un sistema se ignorará en favor de la lista de verificación debajo, porque tenemos prisa y solo necesitamos hacerlo. Y si la advertencia allí queSi realiza ciertos pasos fuera de orden, se borrarán todas sus copias de seguridad.está en ese bloque de texto omitido, tal vez debería tener algún formato que llame la atención, o tal vez incluir esa parte en la lista de verificación también.
Documentación del proceso
Este tipo de documentación trata de describir una forma de hacer algo. Es el más fácil de producir para una persona no entrenada ya que principalmente se trata de escribir una serie de pasos a seguir. En mi experiencia, una buena documentación de procesos tiene las siguientes características:
- Contiene una lista de verificación.
- La lista de verificación se encuentra en la misma página que un breve resumen de cuándo y por qué se ejecuta la lista de verificación.
- Debajo de la lista de verificación, o en una página vinculada, hay un documento más extenso que describe la teoría detrás de la lista de verificación y las variaciones que pueden encontrarse.
Lo desea para que exista la lista de verificación a seguir, y al menos el primer nivel de pasos de solución de problemas ya en la página (o a un clic de distancia), en caso de que sean necesarios.
Este es un formato familiar si alguna vez ha consultado los artículos de Microsoft KB: resumen, reparación, detalles, sistemas afectados. Hay una razón para eso.
Guías de solución de problemas
Esto es más complicado que la documentación del proceso porque hay que codificar árboles de decisión en la documentación. Una lista de verificación simple probablemente no sea suficiente, pero una lista de verificación ramificada, que utilice enlaces a otras listas de verificación, es bastante factible. A este tipo de documentación se aplican las mismas reglas que los documentos de proceso:
- Sea breve, no ahogue al lector en detalles.
- Sea claro sobre cuáles son los puntos de decisión y hacia dónde acudir para las acciones de seguimiento.
- Guarde los antecedentes técnicos detallados para la documentación arquitectónica.
Una guía de solución de problemas puede ser una gran historia de Elige tu propia aventura o puede ser una gran lista con viñetas de todo lo que salió mal en un sistema y lo que lo solucionó.
Documentación de arquitectura
El tipo más difícil de producir, ya que está diseñado para ser material de referencia al que solo harán referencia las personas nuevas que buscan comprender esta cosa compleja en la que acaban de entrar.
La documentación arquitectónica es el documento del por qué. Es por qué se utiliza este sistema y no aquel, cómo están conectados con este otro sistema y qué hizo que esa conexión funcionara de la forma en que lo hizo. Es la documentación que se supone que debe escribir tan pronto como sepa cómo se ve su configuración de producción y actualizarla a medida que se realizan cambios.
En cuanto al formato, tengo que ceder ante los expertos en este caso.
Una buena documentación también es más que solo la plantilla y el formato, una apariencia unificada es buena y mejora la legibilidad; también necesita algunas otras cosas.
Actualizaciones periódicas
Adquiera el hábito de revisar la documentación que ya tiene para asegurarse de que siga siendo buena. Es posible que la lista de verificación para la versión 1.17 no sea buena para la versión 1.26; es hora de actualizarla. Las listas de verificación de memoria necesitan la mayor actualización, ya que incluso los cambios más pequeños en la interfaz de usuario pueden arruinar todo.
Dedicar 10 minutosuna semanarepasar la documentación e identificar las cosas que necesitan limpieza puede hacer cosas increíbles.
La documentación arquitectónica debe ser revisada periódicamente por alguien que conozca el sistema. Como mencioné, estos son documentos que rara vez se usan pero que son muy útiles cuando realmente los necesitas. No desea el documento que describe cómo el clúster de servicios de impresión del campus está conectado con NetWare cuando se realizó la migración a Windows hace 3 años.
Descubrible
Esto es lo más difícil de lograr porque depende en gran medida dedóndeestás almacenando tu documentación.
¿Qué es lo que le decimos a cualquiera que venga a ServerFault con una pregunta?
¿Qué has probado ya?
Seguido poco después por
El mayor éxito en Google resuelve tu problema. Quizás deberías intentarlo.
Buscamos nuestra documentación, no vamos a la estantería. El repositorio de documentación debe ser tan fácil de buscar como Google, o simplemente iremos a Google.
El Repositorio Central de Servilletas es un mal lugar para la documentación, al menos si no tiene un índice en línea (y no lo tendrá). Un wiki simple es mejor ya que la mayoría incluye al menos una búsqueda de texto básica. Un mejor sistema es aquel que permite buscar etiquetas además del texto completo para centrar mejor la búsqueda en las áreas objetivo.
Si está trabajando con un repositorio de documentos que admite etiquetas,estandariza tus etiquetas. Basta con mirar la lista de etiquetas de ServerFault en algún momento para ver por qué. Los usuarios no deberían tener que memorizar las ocho permutaciones devmwaresólo para encontrar lo que están buscando. Esto requerirá esfuerzos ocasionales de reetiquetado.