Several years ago, I heard a story from a colleague. At that time he worked as the head of the technical documentation department at an IT company. It was at a meeting to meet the new CTO. He shook hands with my colleague and learned about his role and joked: “Documentation? So no one reads it! The twenty-first century is in the yard ”.
It is unlikely that any of us would be pleased to be in this man's place. But, colleagues, in all honesty, is it not our fault in such an attitude? Unfortunately, I often come across situations in which the documentation, official or not, cannot help me. But someone wrote it, wasted time and effort. Why was this done? And how can you do better? In this article, I will share my vision of how to write documentation that brings real value to readers.
Perhaps some of what is written in my article will seem "captain's" to you. Nothing wrong! This means that you already know the best practices for writing documentation. The article is primarily addressed to people who have recently come to the profession, therefore, colleagues, if I missed something, or if you have your own view of things - please, unsubscribe in the comments.
What is “good documentation”?
So, let's begin. What is “good documentation” anyway? Detailed? Or written with humor so that it is not boring to read? For some, the best documentation is a thick tome that can be tucked under a table leg to keep it from wobbling. In my opinion, good documentation is one that does its job.
And what is the task of documentation? There can be many answers to this question. The documentation can be used for training, for reference, or even serve as an advertisement. I heard a story from a colleague about how a product manager asked her to write documentation for a new product in three days, emphasizing that "it doesn't matter which one, no one will read it, it is only needed to submit a project." And this is also a task, albeit a very sad one.
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”). : , , . — ! ! .
( , , ). . . , , . , , , “? ! , , ”.
!