Lo he visto
repetidamente.Una de las debilidades más comunes que he visto en compañías de la
ingeniería -- de hecho, una avería casi universal -- es la carencia
de la documentación técnica apropiada. Algunos reirían esto
apagado como detalle de menor importancia; sin embargo, las
repercusiones son a menudo severas. El futuro entero de una
compañía se puede hacer o perder basado en la cantidad de atención
que prestan a esta edición.
Sobre los años, tengo
identificado cinco problemas que he encontrado para ser
particularmente común cuando viene a la documentación técnica de la
escritura. Quisiera compartir estos pensamientos con usted, en la
esperanza de evitar que otros bajen abajo de las mismas trayectorias.
1 No tener cualquieres manuales de usuario
No
ría. Esto puede parecerse como un error bastante básico --
absurdo, incluso -- pero es asombrosamente campo común. He
encontrado a muchas compañías que no proporcionan los manuales de
usuario para sus productos, o que manuales son skeletally finos o
años anticuados. En hecho, estimaría que sobre la mitad de las compañías pequeñas
de la ingeniería que he encontrado caída en esta categoría.
(por supuesto, uno encuentra raramente este problema al comprar
software o electrónica de consumidor disponible. Entre ingenieros
sin embargo, es una historia depressingly familiar. )
Recuerdo cómo un ingeniero me dijo porqué su compañía no proveió
de ninguna manuales de usuario sus productos. En tonos hushed,él
dijo, "está porque no hacemos ningún dinero escribiendo los
manuales. No es una empresa del manantial de beneficios, tan
nuestra gerencia no desea perder tiempo en esto. "una expresión
molestada se arrastró en su cara, después él inclinó más cercano
y dicho," hemos perdido a tan muchos clientes porque no tenemos
documentación decente. Hable de ser penique-sabio,
libra-absurdo!"
No es justa los clientes que sufren cuando los
manuales son inadecuados o no existentes. ¿Qué sobre los
empleados ellos mismos?¿Qué sucede cuando viene un nuevo ingeniero a bordo, y tiene que
aprender rápidamente? O qué sucede cuando los ingenieros existentes
necesitan familiarizar ¿ellos mismos más con aspectos
desconocedores de sus líneas de productos? La documentación del
usuario, si está escrita correctamente, puede proporcionar una manera
apacible y eficiente de traer hasta la velocidad. Sin ella, serán
forzados para confiar más pesadamente en otros ingenieros para
educarlos, así perdiendo la época de cada uno referido. Las
semanas, si no los meses, de la mano de obra valiosa se pueden
malgastar en esta manera.
2 No tener documentación
interna apropiada
No es justa la documentación del usuario en la
cual las compañías faltan. Interno la documentación es con
frecuencia una muerte también, pues las compañías revuelven para
lanzar un producto. En su rapidez para traer productos al mercado,
las compañías dejan a menudo sus documentos internos del diseño
caer desesperado por el wayside.
No ayuda que los programadores y los ingenieros son notorios para
tener habilidades deslustradas de la comunicación, y que la
documentación es una tarea de que gozan raramente. He encontrado
muchas compañías del software, por ejemplo, del las cuales diseños
del software eran un lío insuperable debido a su carencia
documentos, descripciones del interfaz y comentarios arquitectónicos
del en-co'digo. Tristemente, he visto los problemas similares
cuando viene a los diseños mecánicos, diseños electrónicos,
procedimientos de fabricación... usted nombre él.
He
hablado a los ingenieros que han ido compañías debajo, o he estado
vacilando en el borde. Casi invariable, la carencia de la
documentación adecuada ha sido un factor importante en tales
situaciones.
Digo siempre mis jefes y los compañeros de
trabajo, "deseo cerciorarme de que mi trabajo darned bien documentara. Si me voy la compañía, o si muero en un accidente de coche,
porque yo deseamos cerciorarse de que esta compañía pueda marchar
encendido sin mí. "que debe ser una de las razones primeras detrás de guardar la
documentación cuidadosa -- para cerciorarse de que ninguna ausencia
de la persona no lisiará a la compañía.
Desafortunadamente, muchos empleados toman la tachuela opuesta.
Escatiman adrede en la documentación, pensando que ésta les
asegurará una cierta seguridad en el empleo -- y a veces, ésta
trabaja. Sin embargo, un patrón elegante sabe que un ingeniero
que documente bien vale lejos más que otro ingeniero que guarde
sus tarjetas cerca de su chaleco. El último puede ser esencial en
corto plazo, pero en última instancia, él es una responsabilidad a
largo plazo.
3 Olvidarse de sus audiencias
Este
problema ocurre a menudo al desarrollar la documentación del usuario. Los programadores y los ingenieros se olvidan con frecuencia de
que sus manuales van a ser leídos por la gente que son desconocedora
con sus productos, o que no tiene las mismas habilidades técnicas.Recuerdo a una compañía en detalle -- regulador de la máquina
compañía en la costa del oeste. Su "manual de usuario" era una
mezcolanza horrible de las siglas, términos indefinidos y
pensamientos aparentemente al azar, con alrededor los procedimientos
de una docena enumerados en ninguna orden particular. Su
documentación del usuario careció los detalles básicos tales como
cómo comenzar el regulador para arriba, o cómo pararlo en el caso de
una emergencia -- los detalles críticos que cualquier usuario del
neófito debe esperar que encuentren en un manual.
Un
problema relacionado es la falta de utilizar lengua apropiada.
Considere el caso en el cual muchos de los lectores no están las
personas de habla inglesa nativas -- diga, cuando comercialización un
producto en Europa o Asia, o al escribir los procedimientos de la
asamblea para los trabajadores de fábrica foreign-born. En tales
casos, puede ser necesario mantener la lengua bastante simple.Si esto no es posible -- diga, al discutir los detalles complejos que
exigen la precisión mucha -- una puede compensar a menudo agregando
algunas cartas, diagramas o fotografías conveniente-elegidos.
Cualquier acercamiento puede ser provechoso en la fabricación texto
complejo de un pedacito más fácil absorber.
4 No
siendo convenientemente gráfico
Es innegable cliché, pero
verdad no obstante -- un cuadro pinta mil palabras.
Semejantemente, un manual que el uso juicioso de las marcas de
imágenes y de diagramas será mucho más fácil entender que uno que
se compone enteramente de descripciones del texto.
Algunos
consideran esto ser infantil e innecesario. No , y mi experiencia
ha demostrado que la mayoría de usuarios aprecia tener estas guías
visuales. Recuerde; no importa cómo está sofisticado sus
lectores sea, siguen siendo ser humano. Incluso un inteligente,
si noel lector cuidadoso puede faltar accidentalmente un cierto detalle
importante, especialmente cuando está presionado por tiempo.
5 No esforzándose para la excelencia
Es interesante
ver cómo los programadores y los ingenieros pueden esforzarse para la
excelencia en muchos aspectos de su trabajo, con todo toma el exacto
enfrente de acercamiento cuando viene a la documentación.
"quién cuida sobre redactar de todos modos?" He oído que muchos
ingenieros dicen. "no estamos escribiendo poesía o los guiones
aquí. Qué importa es que la documentación debe ser técnico
exacta. "
Éste es visión espantoso miope. La
exactitud técnica es de hecho importante, pero así que son la
presentación y el estilo. ¡Pocos ingenieros escucharían un
aspirante del trabajo que demuestra para arriba en un albornoz y
deslizadores, o un abogado del pleito que habla como una muchacha del
valle -- pero de alguna manera, estos mismos ingenieros cuentan con
sus techies del compañero (o peores, cliente!) para slog a través de las páginas del serpenteo, texto mal
expresado. Incluso las materias tan fundamentales como el
deletreo, la gramática y corregir se tratan a menudo como molestias
meras -- detalles piddling eso no valga nada más que un vistazo
precipitado.
(a mi relevación, no he encontrado
cualesquiera actitudes en mi lugar del empleo. ¡Acelero decir
esto, a fin de cualquier persona piense que me estoy quejando por la
gente con quien trabajo! No, he encontrado que todos apreciamos el
valor de la excelencia, para el cual soy siempre agradecido. Pero
digress. )
Recuerde: Al escribir para sus techies del
compañero, uno debe considerar que deben absorber a menudo cantidades
de información voluminosas en cantidades de tiempo escasas.
Cuando escribiendo para los laicos, uno debe hacer el texto tan
apacible y fácil digerir como sea posible, a fin de lleguen a ser
perdidas en un océano del geekspeak.Cualquier manera, poniendo un poco esfuerzo adicional en materias de
la elegancia y del estilo puede hacer un mundo de diferencia.
No entraré el detalle sobre qué constituye buena técnica de la
escritura, como que estaría más allá del alcance de este texto. Sea suficiente decir que un buen programador o ingeniero debe
cerciorarse de que su escritura sea legible y bien-organizada, y que
fluye suavemente de un asunto a otro.
Me
emocionarían más allá de creencia si nunca vi otro manual
descuidado, o si nunca oí otra historia sobre derrumbarse de las
compañías debido a la documentación no existente. ¿Una
fantasía desesperada? Quizá. No obstante, espero que algunos
techies hacia fuera allí lean este mensaje, y que lo llevarán el
corazón.
