Beberapa tahun yang lalu, saya mendengar cerita dari seorang rekan. Saat itu ia bekerja sebagai kepala departemen dokumentasi teknis di sebuah perusahaan IT. Itu pada pertemuan untuk bertemu CTO baru. Dia berjabat tangan dengan rekan saya dan mengetahui tentang perannya dan bercanda: “Dokumentasi? Jadi tidak ada yang membacanya! Abad kedua puluh satu ada di halaman ”.
Tidak mungkin salah satu dari kita akan senang berada di tempat pria ini. Tapi, rekan-rekan, sejujurnya, bukankah salah kita dalam sikap seperti itu? Sayangnya, saya sering menemukan situasi di mana dokumentasi, resmi atau tidak, tidak dapat membantu saya. Tetapi seseorang menulisnya, membuang-buang waktu dan tenaga. Mengapa ini dilakukan? Dan bagaimana Anda bisa lebih baik? Dalam artikel ini, saya akan membagikan visi saya tentang bagaimana menulis dokumentasi yang memberikan nilai nyata bagi pembaca.
Mungkin beberapa dari apa yang tertulis dalam artikel saya akan tampak "kapten" bagi Anda. Tidak ada yang salah! Ini berarti Anda sudah mengetahui praktik terbaik untuk menulis dokumentasi. Artikel ini terutama ditujukan kepada orang-orang yang baru saja datang ke profesi ini, oleh karena itu, kolega, jika saya melewatkan sesuatu, atau jika Anda memiliki pandangan Anda sendiri tentang berbagai hal - silakan berhenti berlangganan di komentar.
Apa itu "dokumentasi yang baik"?
Jadi, mari kita mulai. Apa itu "dokumentasi yang baik"? Terperinci? Atau ditulis dengan humor agar tidak membosankan untuk dibaca? Bagi sebagian orang, dokumentasi terbaik adalah buku tebal yang dapat diselipkan di bawah kaki meja agar tidak goyah. Menurut pendapat saya, dokumentasi yang baik adalah yang melakukan tugasnya.
Dan apa tugas dokumentasi? Ada banyak jawaban untuk pertanyaan ini. Dokumentasi tersebut dapat digunakan untuk pelatihan, referensi, atau bahkan sebagai iklan. Saya mendengar cerita dari seorang rekan tentang bagaimana seorang manajer produk memintanya untuk menulis dokumentasi untuk produk baru dalam tiga hari, menekankan bahwa "tidak masalah yang mana, tidak ada yang akan membacanya, hanya perlu mengirimkan proyek ." Dan ini juga merupakan tugas, meskipun sangat menyedihkan.
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”). : , , . — ! ! .
( , , ). . . , , . , , , “? ! , , ”.
!