Hace varios años, escuché una historia de un colega. En ese momento trabajaba como jefe del departamento de documentación técnica en una empresa de TI. Fue en una reunión para conocer al nuevo CTO. Estrechó la mano de mi colega, se enteró de su papel y bromeó: “¿Documentación? ¡Entonces nadie lo lee! El siglo XXI está en el patio ”.
Es poco probable que alguno de nosotros esté complacido de estar en el lugar de este hombre. Pero, colegas, con toda honestidad, ¿no es culpa nuestra esta actitud? Desafortunadamente, a menudo me encuentro con situaciones en las que la documentación, oficial o no, no puede ayudarme. Pero alguien lo escribió, desperdició tiempo y esfuerzo. ¿Por qué se hizo esto? ¿Y cómo puedes hacerlo mejor? En este artículo, compartiré mi visión de cómo escribir documentación que brinde un valor real a los lectores.
Quizás algo de lo que está escrito en mi artículo le parezca "del capitán". ¡Nada mal! Esto significa que ya conoce las mejores prácticas para redactar documentación. El artículo está dirigido principalmente a personas que han llegado recientemente a la profesión, por lo tanto, colegas, si me perdí algo o si tienen su propia visión de las cosas, cancelen la suscripción en los comentarios.
¿Qué es una “buena documentación”?
Vamos a empezar. ¿Qué es una "buena documentación" de todos modos? ¿Detallado? ¿O escrito con humor para que no sea aburrido de leer? Para algunos, la mejor documentación es un tomo grueso que se puede colocar debajo de la pata de una mesa para evitar que se tambalee. En mi opinión, una buena documentación es aquella que hace su trabajo.
¿Y cuál es la tarea de la documentación? Puede haber muchas respuestas a esta pregunta. La documentación se puede utilizar para formación, como referencia o incluso como publicidad. Escuché una historia de un colega sobre cómo un gerente de producto le pidió que escribiera documentación para un nuevo producto en tres días, enfatizando que "no importa cuál, nadie lo leerá, solo es necesario enviar un proyecto . " Y esta también es una tarea, aunque muy triste.
Plesk — , , . , , , , .
, . ? , , ? , , Plesk, . ...
, , . , . , , . , (findability).
. , () :
Plesk.
.
.
, Google .
, Google Search Console “”. “plesk login”, “plesk install”, “plesk ftp” . , , , . , , . .
, “ ” “ ”. , , . , . , , , , .
, . , , . , , , “ ”. Nielsen Norman Group , , .
, ? — ( - ) , , . , , , . :
, FTP Plesk. , FTP , .
, .
, , , , , , , .
-: „ , , , “. , , — . ?
, , : “ , , ”. .
: , . , . , , . , , .
, ? , , , . , , .
. , , , , Chrome. , . ? , , , . , - . , - (" — "), , . .
, . — -, — , , . “ ”. Ok, .
, , . - , , , , . , , “ ”. , - , ( , SSL , ).
, , , , , . “, , , , ?” :
, .
.
. , , .
, , , . , , .
, . , , , . :
?
?
?
, , -, , -, , ( ) .
Plesk “Every page is page one” (EPPO) . , , , :
, , , . , .
, , . , , , .
, EPPO : .
. , SSL , Plesk :
(certificate signing request) (certificate authority).
.
.
, , , ( SSL ) .
EPPO, , , . , , “ Plesk” “ Plesk ”, — , . , , , .
, , , . SaaS-, , , . , , Microsoft Google.
, , , . , , , . , , , , . , ?
, , :
, , .
, .
, , . Plesk , .
, , — “ ” (curse of knowledge). , , . - “-, ”, , .
, . , , , . , Git, , , , , SSH . “, , ”, , “”, .
: . :
: “ , ? , !”
: “ , . , , .”
, ? , . , , , “ ”, . , , . ? , , . , (“ ” “ ”) — , , (, ).
— , , . , . , , , . " " (decision support).
. Plesk SpamAssassin. (spam filter sensitivity) , . : , 127. , . “” :
“Spam filter sensitivity” Ok.
, . , SpamAssassin, , . ?
( 0 127) “Spam filter sensitivity” Ok. , , , , .
? :
( 0 127) “Spam filter sensitivity” Ok. , , , , . — 7, .
, , , . , , , , , , (, ).
? . , . ( , ) . (, , , , , INSERT UPDATE ), , , .
, , , . , “ ”. . , , , , , , . “ — ” , “ ”.
, Plesk. , , . : “ ” (“Write one good page”). : , , . — ! ! .
( , , ). . . , , . , , , “? ! , , ”.
!