Setiap layanan yang disediakan oleh Selectel dapat dikelola di akun pribadi Anda - panel kontrol . Banyak dari produk kami juga dapat dikontrol melalui permintaan API. Petunjuk produk dan dokumentasi API tersedia di satu pusat bantuan .
Ide utama dari pusat bantuan ini adalah memberikan kesempatan kepada klien kami untuk menemukan jawaban secara mandiri atas sebagian besar pertanyaan mereka tentang layanan Selectel kapan saja sesuai keinginan mereka.
Selanjutnya, kita akan berbicara tentang bagaimana kita mengubah pendekatan untuk menyiapkan dokumentasi dan memperbarui tampilan basis pengetahuan.
Pelaksanaan teknis dari basis pengetahuan dan komponen visualnya tiga tahun yang lalu memenuhi semua kebutuhan buku referensi dengan informasi. Namun selama ini perusahaan tidak berhenti, melainkan terus berkembang secara aktif, baik meluncurkan layanan baru maupun mengembangkan layanan yang sudah ada.
Sekitar setahun yang lalu, kami melihat bahwa bantuan online yang ada tidak memenuhi persyaratan pelanggan kami:
- menu navigasi tumbuh seperti pohon buah-buahan yang tidak mengenal perawatan seorang tukang kebun;
- pencarian tidak lagi nyaman;
- desain visual secara bertahap menjadi usang.
Sebelumnya, dokumentasi untuk API produk kami tidak tersedia untuk umum - beberapa diposting di panel kontrol my.selectel.ru , beberapa dikeluarkan atas permintaan, dan beberapa dijelaskan secara lengkap dalam format teks, yang selalu diperbarui sangat bermasalah. Sekarang pengetahuan tentang otomatisasi infrastruktur TI dan interaksi dengan backend layanan Selectel di tab Dokumentasi API .
Sebuah tamasya kecil ke masa lalu
Sepuluh atau lima belas tahun yang lalu, beberapa perusahaan yang memproduksi perangkat lunak di Rusia dapat membanggakan bantuan online. Panduan pengoperasian ditulis dalam format Word dengan menggunakan gaya yang selalu bergerak, mencoba menerapkan standar GOST yang dibuat pada tahun 70-an abad ke-20 dengan persyaratan modern dan terus berubah.
Meme itu masih populer di kalangan penulis teknis:
Hingga hari ini, ada perusahaan yang sudah dapat membanggakan antarmuka situs yang nyaman, tetapi dokumentasinya tetap pada tingkat "petunjuk unduhan dalam format pdf untuk 45 lembar."
Di perusahaan besar, basis pengetahuan sangat terkait dengan dukungan teknis. Dalam dunia bulat yang ideal dalam ruang hampa, pengguna harus dapat menemukan 80% jawaban atas pertanyaan mereka secara mandiri, tanpa menghubungi dukungan teknis.
Portal dengan dokumentasi tidak menghasilkan keuntungan yang jelas, tetapi dapat menghemat waktu dukungan teknis karena skrip:
- Pengguna memesan layanan.
- Dihadapkan dengan momen yang tidak terlihat saat menyiapkan.
- Saya ingin menghubungi dukungan teknis.
- Saya pergi ke basis pengetahuan dan menemukan informasi yang saya butuhkan sendiri.
- Tidak menghubungi dukungan teknis.
- Keuntungan!)
Seringkali diyakini bahwa informasi bantuan hanya membantu pengguna memahami layanan setelah mereka terhubung. Ini mungkin terjadi pada hari-hari ketika buku cetak dengan informasi tentang bekerja di Windows diterbitkan. Tapi sekarang menjadi sama pentingnya untuk menunjukkan secara terbuka kepada calon pengguna bagaimana layanan beroperasi sebelum membeli.
Sebagian besar perusahaan perangkat lunak mengembangkan API untuk penggunaan internal dan pelanggan di beberapa titik. Perusahaan berbagi serangkaian masukan dengan merilis API publik untuk memungkinkan pelanggan mengintegrasikan layanan mereka dengan produk perusahaan.
Banyak tugas khusus dapat diotomatiskan, termasuk menggunakan potongan kode yang sudah jadi sebagai konstruktor untuk membuat infrastruktur yang paling ramah pengguna. Tetapi potongan kode tanpa penjelasan tentang apa itu, apa yang dilakukannya, dan bagaimana menggunakannya tidak banyak berguna - Anda tidak akan menggunakan kekerasan untuk mencari tahu metode apa dan data apa yang ingin mereka masukkan.
- Apa yang perlu dilakukan agar API publik nyaman digunakan?Sebagai dokumentasi untuk API, mereka biasanya memberikan contoh interaksi minimal, yang menjelaskan metode (juga disebut endpoint) dan memberikan respons dari layanan. Misalnya, menggunakan Kubernetes API, Anda dapat mengotomatiskan pekerjaan dengan cluster dan node di Managed Kubernetes .
- Lampirkan dokumentasi!
Tugas apa yang ada di hadapan kita
Solusi visual kami berhenti mempermudah menemukan artikel yang kami butuhkan, dan menu yang ada berubah menjadi "sheet" yang tidak dapat dibaca. Dokumentasi yang tidak dapat dibaca sama buruknya dengan teks yang tidak relevan. Orang-orang terbiasa membaca materi yang ditata dengan baik. Blog, jejaring sosial, media - semua konten disajikan tidak hanya cantik, tetapi juga mudah dibaca, enak dipandang. Saat ini, persyaratan UX dan UI tidak dapat diabaikan, terutama untuk sejumlah besar teks.
Dengan perkembangan teknologi untuk desain visual situs, kami melihat bahwa tampilan basis pengetahuan kami sudah ketinggalan zaman. Hanya menggunakan jangkar dan daftar di artikel KB tidak membantu. Seluruh struktur dokumentasi dan mekanisme pencarian perlu direvisi.
Masalah umum dengan dokumentasi
Umumnya tidak ada atau tidak ada yang tahu tentang keberadaannya,
instruksi yang tidak dapat ditemukan tidak lebih baik dari instruksi yang tidak ada.
Kami memecahkan masalah ini dengan cara berikut - kami mulai menambahkan tautan ke artikel berguna di milis bulanan kami, menambahkan transisi pada halaman produk situs, dan juga mengatur pemberitahuan untuk semua karyawan perusahaan yang tertarik melalui saluran khusus di utusan perusahaan.
Usang dan tidak diperbarui dalam waktu
Proses dokumentasi tidak dibangun ke dalam pengembangan produk, dokumentasi dilakukan berdasarkan sisa.
Dalam kasus kami, manajer produk juga ditugaskan untuk mendokumentasikan fungsionalitas baru ini sambil mengerjakan fungsionalitas baru.
Dokumentasi rumit dan tidak terorganisir dengan baik, lebih mudah untuk bertanya kepada dukungan teknis bagaimana menyelesaikan masalah
Menulis dokumentasi untuk kepentingan dokumentasi tidak ada gunanya, harus mudah diakses. Semakin banyak opsi untuk menemukan dokumen, semakin baik.
Kami sepenuhnya merevisi desain bagian dari basis pengetahuan kami, dalam beberapa kasus template universal tidak berfungsi, jadi kami harus berinteraksi secara aktif dengan semua pemangku kepentingan, baik itu manajer produk, dukungan teknis, atau tim pengembangan front-end.
Memindahkan dokumentasi API ke ruang publik
Salah satu masalah dengan penggunaan dokumentasi API yang dihasilkan di OpenAPI, Swagger, atau beberapa alat generasi lainnya adalah integrasi yang kompleks dengan situs lainnya. Pengguna harus memiliki akses bebas masalah ke semua instruksi dan artikel - tidak nyaman jika titik akhir ditampilkan dalam satu tampilan, dan deskripsi teks dari proses yang sama ditampilkan di halaman lain.
Mempertahankan satu gambar visual
Saat membuat satu pusat bantuan, kami perlu mempertahankan tampilan petunjuk dan spesifikasi yang konsisten, menggunakan sekumpulan "git + markdown + swagger".
Bagaimana cara kerjanya sekarang
Implementasi teknis
Basis pengetahuan awalnya dibangun di sekitar kombinasi Confluence dan generator halaman statis.
Kami membuang Confluence dan beralih ke Documentation-as-Code. Sekarang semua kode sumber untuk basis pengetahuan diatur dalam format penurunan harga dan disimpan dalam sistem penyimpanan versi Git. Situs basis pengetahuan dibangun dari repositori menggunakan Generator Situs Statis Hugo.
Situs ini dihasilkan dari file yang ada di cabang master dari repositori Git. Data hanya dapat diperbarui melalui pull-request, yang memungkinkan Anda memeriksa semua bagian baru dari dokumentasi sebelum dipublikasikan di domain publik. Sistem seperti itu juga memfasilitasi pendekatan untuk melakukan pengeditan - karyawan perusahaan selalu dapat membuat cabang dan menambahkan semua perubahan yang diperlukan.
Lebih lanjut tentang Dokumentasi sebagai Kode
Prinsip "dokumentasi sebagai kode" menyiratkan penggunaan alat yang sama untuk menulis dokumentasi seperti untuk membuat kode:
- bahasa markup teks;
- sistem kontrol versi;
- review kode.
Tujuan utama dari pendekatan ini adalah untuk menciptakan kondisi untuk kerja bersama seluruh tim pada hasil akhir - basis pengetahuan dan instruksi yang lengkap untuk menggunakan layanan produk individu.
Bekerja dengan file kesombongan
Pengembang produk Selectel membuat API dan mengunggah komentar ke kode dalam format swagger - ini adalah file teks dalam format * .yaml yang dapat digunakan sebagai kode. Saat API diperbarui, file swagger juga diperbarui, sehingga lebih mudah untuk memperbarui dokumentasi.
Solusi teknis berikut digunakan untuk dokumentasi API:
- git repository dengan file spesifikasi swagger dalam format * .yaml, dikelompokkan berdasarkan produk;
- repositori git dengan terjemahan spesifikasi kesombongan dalam format * .json;
- repositori git dengan file dalam format * .md;
- file dalam format * .md berisi deskripsi teks dan dibungkus dalam tag deskripsi titik akhir khusus yang ditarik dari repositori git dengan file dalam format * .json;
- Generator situs statis Hugo.
Selain struktur repositori, aturan untuk bekerja dengannya dikembangkan:
- panduan gaya telah disiapkan - daftar periksa untuk file swagger, yang diperiksa oleh pengembang saat memperbarui spesifikasi API;
- cabang master dari repositori git dengan file dalam format * .md mencerminkan status spesifikasi saat ini dan secara de facto dalam produksi;
- Pull-Request ke cabang master dilakukan saat update dirilis ke produksi.
Komponen visual
Langkah pertama adalah merevisi navigasi dan membuat aturan yang sesuai dengan bagian dari basis pengetahuan yang akan dibentuk. Bersama dengan desainer UX, kami menyiapkan arsitektur informasi. Strukturnya harus setransparan mungkin sehingga pembaca tidak berpikir: "Di mana Anda dapat menemukan artikel ini?" Untuk meringkas, ada dua pendekatan:
- Dari antarmuka. Konten menduplikasi bagian panel (secara terpisah untuk layanan). Ini adalah kasus di basis pengetahuan versi sebelumnya.
- Dari tugas. Judul artikel dan bagian mencerminkan tugas pengguna.
Untuk merampingkan struktur, kami menggunakan kombinasi dari dua pendekatan ini. Bahkan dalam versi panel kontrol yang lebih baru dengan UX dan UI yang dipikirkan dengan matang, perlu dijelaskan setidaknya persyaratannya, karena produk kami secara teknis rumit dan penggunanya sangat berbeda.
Selain memperbarui daftar isi, kami telah menyempurnakan penelusuran dan runut tautan. "Breadcrumbs" adalah jalur pengguna ke halaman saat ini dengan kemampuan untuk kembali ke level mana pun. Pada versi sebelumnya dari basis pengetahuan, tidak mungkin untuk masuk ke daftar isi dan itu tidak nyaman, jadi di versi baru kami telah memperbaikinya.
Setiap perusahaan membuat dokumentasi API sesuai dengan visinya sendiri tentang gaya, struktur, dan rasa keindahan. Jika kami membuka 4-5 API publik dari perusahaan yang berbeda, maka, tidak diragukan lagi, kami akan dapat menangkap beberapa kesamaan: struktur, contoh kode yang banyak dan penyorotan sintaks, halaman panjang. Meskipun demikian, semua contoh akan memiliki ciri khusus. Misalnya, pelokalan deskripsi titik akhir jarang terjadi, sedangkan struktur deskripsi titik akhir paling sering terlihat sama.
Beberapa rekomendasi penataan dokumentasi API:
Pengelompokan endpoint
Selain memberikan informasi untuk setiap endpoint, jika terdapat banyak endpoint, disarankan untuk mengelompokkannya. Daftar titik akhir yang panjang dan terus menerus membuat navigasi menjadi sulit.
Deskripsi metode terpisah
Saat menggunakan metode GET / POST secara bersamaan, hanya satu metode yang harus dijelaskan dalam satu baris.
Artinya, baris pertama dalam hal ini adalah deskripsi GET, baris kedua adalah deskripsi POST, sehingga Anda dapat menghindari kebingungan.
Otomatisasi membuat perubahan
Sederhanakan membuat perubahan tanpa memformat ulang setiap bagian secara manual - dalam kasus kami, kami hanya menerjemahkan teks dari file swagger, tanpa menyentuh markup berkat otomatisasi proses ini yang telah dikonfigurasi oleh pakar developer kami.
Penyorotan sintaksis
Pengembang paling menyukai contoh kode di dunia, tidak ada pengembang yang akan mengeluh bahwa ada terlalu banyak contoh - mereka sangat mengurangi waktu untuk tenggelam dalam produk.
Bekerja dengan potongan kode jauh lebih mudah ketika elemen yang berbeda diwarnai dengan tepat tergantung pada bahasa pemrograman.
Karena penyorotan kode out-of-the-box hanya tersedia untuk latar belakang gelap, pengembang frontend memodifikasi solusi ini menggunakan highlight.js untuk gaya perusahaan kami.
Alih-alih kesimpulan
Basis pengetahuan yang diperbarui telah tersedia untuk pengguna sejak Maret, dan dokumentasi API telah tersedia sejak awal Agustus.
“- Bersama kami, ketika Anda berlari untuk waktu yang lama, Anda pasti menemukan diri Anda berada di tempat lain.Apa yang telah kami lakukan hanyalah langkah lain untuk meningkatkan basis pengetahuan. Kami secara bertahap akan menambahkan instruksi dan dokumentasi baru ke API layanan kami yang lain.
“Nah, di sini, kamu tahu, kamu harus lari secepat mungkin untuk tetap di tempat yang sama, dan untuk sampai ke tempat lain, kamu harus lari dua kali lebih cepat.”
(Lewis Carroll "Alice Through the Looking Glass")