Comment rédiger une bonne documentation

Il y a plusieurs années, j'ai entendu une histoire d'un collègue. A cette époque, il travaillait comme chef du département de documentation technique dans une société informatique. C'était lors d'une réunion pour rencontrer le nouveau CTO. Il a serré la main de mon collègue et a appris son rôle et a plaisanté : « La documentation ? Alors personne ne le lit ! Le XXIe siècle est dans la cour ».

Il est peu probable que l'un d'entre nous serait heureux d'être à la place de cet homme. Mais, chers collègues, en toute honnêteté, n'est-ce pas de notre faute dans une telle attitude ? Malheureusement, je rencontre souvent des situations dans lesquelles la documentation, officielle ou non, ne peut pas m'aider. Mais quelqu'un l'a écrit, a perdu du temps et des efforts. Pourquoi cela a-t-il été fait ? Et comment faire mieux ? Dans cet article, je partagerai ma vision de la manière de rédiger une documentation qui apporte une réelle valeur ajoutée aux lecteurs.

Peut-être qu'une partie de ce qui est écrit dans mon article vous semblera « de capitaine ». Rien de mal! Cela signifie que vous connaissez déjà les meilleures pratiques pour rédiger de la documentation. L'article s'adresse principalement aux personnes qui sont récemment arrivées dans la profession, donc, collègues, si j'ai raté quelque chose, ou si vous avez votre propre vision des choses - s'il vous plaît, désabonnez-vous dans les commentaires.

Qu'est-ce qu'une « bonne documentation » ?

Alors, commençons. Qu'est-ce qu'une « bonne documentation » ? Détaillé? Ou écrit avec humour pour que ce ne soit pas ennuyeux à lire ? Pour certains, la meilleure documentation est un tome épais qui peut être caché sous un pied de table pour l'empêcher de vaciller. À mon avis, une bonne documentation est celle qui fait son travail.

Et quelle est la tâche de la documentation? Il peut y avoir plusieurs réponses à cette question. La documentation peut être utilisée à des fins de formation, de référence ou même de publicité. J'ai entendu une histoire d'un collègue sur la façon dont un chef de produit lui a demandé d'écrire la documentation d'un nouveau produit en trois jours, soulignant que "peu importe lequel, personne ne le lira, il suffit de soumettre un projet ." Et c'est aussi une tâche, bien que très triste.

Plesk — , , . , , , , .

, . ? , , ? , , Plesk, . ...

, , . , . , , . , (findability).

. , () :

1. Plesk.

   
   
   
   
   

2. .

   
   
   
   
   

3. .

   
   
   
   
   

4. , Google .

   
   
   
   
   

, Google Search Console “”. “plesk login”, “plesk install”, “plesk ftp” . , , , . , , . .

, “ ” “ ”. , , . , . , , , , . 

, . , , . , , , “ ”. Nielsen Norman Group , , .

, ? — ( - ) , , . , , , . :

, FTP Plesk. , FTP , .

, .

, , , , , , , .

-: „ , , , “. , , — . ?

• . , “ ” “ ”.

  
  
  
  
  

• .

  
  
  
  
  

• (4-6 ) .

  
  
  
  
  

, , : “ , , ”. .

: , . , . , , . , , .

, ? , , , . , , .

. , , , , Chrome. , . ? , , , . , - . , - (" — "), , . .

, . — -, — , , . “ ”. Ok, .

, , . - , , , , . , , “ ”. , - , ( , SSL , ).

, , , , , . “, , , , ?” :

• , .

  
  
  
  
  

• .

  
  
  
  
  

• . , , .

  
  
  
  
  

• , , , . , , .

  
  
  
  
  

, . , , , . :

• ?

  
  
  
  
  

• ?

  
  
  
  
  

• ?

  
  
  
  
  

, , -, , -, , ( ) .

Plesk “Every page is page one” (EPPO) . , , , :

• , , , . , .

  
  
  
  
  

• , , . , , , .

  
  
  
  
  

, EPPO : .

. , SSL , Plesk :

1. (certificate signing request) (certificate authority).

   
   
   
   
   

2. .

   
   
   
   
   

3. .

   
   
   
   
   

, , , ( 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”). : , , . — ! ! .

( , , ). . . , , . , , , “? ! , , ”.

!

P.S. “!” .