Kenapa Susah Membuat Dokumentasi? Buat Dokumen Produk Cantik Tanpa Coding

Mencari cara untuk merampingkan proses dokumentasi produk Anda tanpa memerlukan keahlian teknis? Apidog menawarkan solusi komprehensif yang memberdayakan manajer produk dan tim operasional untuk berkolaborasi dengan lancar dalam membuat, mengelola, dan menerbitkan dokumentasi profesional. Dengan antarmuka yang intuitif, fitur kolaborasi waktu nyata, dan penerbitan tanpa pemeliharaan, Apidog mengubah cara tim mendekati alur kerja dokumentasi. Setiap produk membutuhkan dokumentasinya sendiri. Meskipun produk Anda adalah aplikasi yang berhadapan langsung dengan konsumen dengan desain interaksi yang sangat intuitif dan sederhana, akan tetap ada area yang memerlukan penjelasan lebih lanjut, namun akan menambah kerumitan jika disajikan langsung di antarmuka produk. Oleh karena itu, manajemen, pemeliharaan, dan penerbitan dokumen adalah perhatian krusial bagi setiap produk. Saat membangun dokumentasi produk, tim biasanya menggunakan alat dokumentasi siap pakai seperti Notion, atau alat manajemen konten seperti Confluence dan CMS, atau generator dokumentasi seperti Docusaurus dan Gitbook. Namun, solusi-solusi ini seringkali menghadapi masalah-masalah berikut: 1.  Dokumentasi membutuhkan pengkodean untuk ditulis, dengan biaya tinggi. Bahkan setelah dokumentasi ditulis, pengalaman membaca yang sebenarnya seringkali jauh dari harapan; 2.  Dokumentasi melibatkan kolaborasi berbagai peran, membuat manajemen versi sulit dan menyulitkan komunikasi saran optimasi kepada orang lain; 3.  Menerbitkan dokumentasi yang sudah jadi ke lingkungan produksi terlalu sederhana atau terlalu kompleks, berpotensi melibatkan proses rekayasa yang sulit ditangani oleh rekan non-teknis, menyebabkan kesalahan. Tim Apidog sebelumnya menggunakan Docusaurus untuk membuat dokumentasi kami. Seiring dengan terus beriterasinya dokumentasi kami, kami juga menghadapi beberapa masalah yang disebutkan di atas. Setelah merangkum pengalaman dan pelajaran yang kami dapatkan, kami mengembangkan solusi dan mengintegrasikannya ke dalam Apidog. Kini, dokumentasi produk tim Apidog telah sepenuhnya dimigrasikan ke Apidog, dengan semua pembuatan dan presentasi ditangani oleh Apidog. Saya akan berbagi praktik kami tentang cara membangun dokumentasi produk melalui Apidog. Sebelum itu, jika Anda ingin melihat lebih dekat efek spesifik dari dokumentasi produk Apidog, Anda dapat memeriksa dokumentasi bantuan Apidog – umpan balik sangat kami nantikan. ## Latar Belakang Sebelum memperkenalkan praktik kami, ada beberapa konteks yang mungkin perlu dijelaskan terlebih dahulu, agar semua orang dapat lebih memahami mengapa kami melakukan hal ini. Dokumentasi produk perusahaan kami umumnya dibuat secara kolaboratif oleh rekan-rekan dari departemen produk dan operasional. Proses utamanya adalah sebagai berikut: Proses di atas tidak memerlukan keterlibatan personel teknis – semua operasi terkait dokumentasi produk diselesaikan oleh rekan-rekan dari kedua departemen ini. Selanjutnya, saya akan menjelaskan cara menyelesaikan tugas membangun dokumentasi produk melalui Apidog sesuai dengan proses ini. ## Proses Inti ### 1. Buat Cabang Sprint untuk Manajemen Konten dan Kolaborasi Setelah iterasi pengembangan dimulai, rekan-rekan operasional membuat cabang iterasi di Apidog untuk menempatkan semua dokumen yang melibatkan perubahan dalam iterasi saat ini di dalam cabang ini untuk kolaborasi, menghindari dampak langsung pada cabang utama. Setelah pembuatan, manajer produk mengimpor dokumen yang ada yang memerlukan modifikasi ke cabang iterasi ini berdasarkan fitur yang benar-benar diperbarui dalam iterasi, dan membuat dokumen baru untuk fitur baru langsung di cabang iterasi. Operasi di sini sepenuhnya konsisten dengan penggunaan cabang iterasi untuk dokumentasi API. Karena kami telah menetapkan perlindungan pada cabang utama, perubahan langsung pada konten dokumen di cabang utama tidak diizinkan. Ini berarti Anda tidak dapat secara manual mengubah konten dalam dokumentasi yang diterbitkan yang dapat dilihat langsung oleh pengguna, membuat dokumentasi produk lebih stabil dan mengurangi situasi di mana perubahan acak menyebabkan konten yang salah dilihat oleh pengguna. ### 2. Gunakan Editor Markdown yang Indah untuk Menulis Setiap Dokumen Manajer produk akan menggunakan Markdown untuk menulis dokumentasi yang perlu diperbarui dalam iterasi saat ini di dalam cabang iterasi. Fungsionalitas Markdown Apidog sangat kuat, dengan berbagai komponen visual yang dapat diklik untuk menyisipkan banyak gaya kompleks dengan hambatan masuk yang rendah, memungkinkan Anda menulis artikel yang indah dengan mudah tanpa mengeluarkan usaha ekstra. Selain penyisipan visual gaya MD umum, Apidog telah menambahkan fitur khusus berikut: *   Sisipkan API/dokumen proyek, memungkinkan dokumen saling terhubung membentuk rantai referensi dengan navigasi yang mulus, memberikan pembaca pengalaman yang lebih lancar dan lebih baik dalam memecahkan kebutuhan dan masalah pembaca – ini adalah fitur yang sangat penting. *   Menyediakan fungsi penyisipan sumber daya yang kaya, seperti Ikon, blok sorotan, tabel, langkah-langkah, Mermaid, video, dll., sehingga Anda tidak perlu menghabiskan waktu mencari sumber daya sendiri atau mempelajari sintaks gaya MD untuk membuat dokumen terlihat lebih baik. ### 3. Rekan Produk/Operasional Berkolaborasi untuk Memoles Dokumen Setelah manajer produk menulis versi awal dokumen di cabang iterasi, untuk meningkatkan kualitas dokumen, kejelasan, dan kegunaan bagi pengguna, mereka menyerahkan dokumen tersebut kepada rekan operasional untuk dibaca dari perspektif pengguna dan memberikan saran modifikasi untuk pemolesan. Ini dulunya merupakan bagian yang paling memakan waktu dan melelahkan, membutuhkan kolaborasi timbal balik antara kedua belah pihak, dengan satu pihak menjelaskan ide-ide mereka dan memberikan saran modifikasi spesifik untuk bagian-bagian tertentu; kemudian pihak lain menerima, memahami, dan benar-benar melakukan perubahan. Selama proses bolak-balik, seringkali terjadi berbagai masalah seperti kesalahpahaman, perubahan yang salah, dan perbedaan konten antar versi dokumen, yang menyebabkan efisiensi yang sangat rendah. Kini menggunakan Apidog, kedua belah pihak dapat langsung melakukan modifikasi pada dokumen, dengan notifikasi pesan waktu nyata yang didorong ke IM saat perubahan dilakukan, memungkinkan orang lain segera masuk ke dokumen dan dengan mudah melihat perubahan spesifik, sangat meningkatkan efisiensi kolaborasi. Berikut adalah langkah-langkah spesifiknya: *   Manajer produk membuat versi awal dokumen. Setelah personel operasional melihat notifikasi, mereka membaca dokumen dan langsung melakukan modifikasi pada konten yang ingin mereka ubah di dalam dokumen ini. *   Modifikasi secara otomatis memicu notifikasi saat disimpan, mengirimkan kartu pesan perubahan ke grup IM yang telah dikonfigurasi sebelumnya. Setelah anggota grup melihat kartu pesan ringkasan perubahan, mereka dapat mengklik tautan notifikasi untuk masuk ke dokumen yang relevan dengan satu klik. *   Melalui riwayat modifikasi, bandingkan perbedaan dengan memilih versi saat ini dan versi asli untuk dengan mudah melihat modifikasi pihak lain dan memutuskan cara menyesuaikan dokumen. Anda dapat memilih untuk tidak menerima saran dan mengembalikan ke versi asli, atau menerima modifikasi dan mempertahankan versi terbaru. Tim produk dan operasional mengulang langkah-langkah di atas hingga konten dokumen dipoles dan versi yang disetujui semua orang ditentukan. ### 4. Persiapan dan Tinjauan Sebelum Penerbitan Dokumen Resmi Untuk memastikan bahwa konten dan tangkapan layar produk dalam dokumen sepenuhnya konsisten dengan apa yang dapat diakses pengguna, kami merekomendasikan untuk mengambil tangkapan layar di lingkungan produksi produk. Ini juga memungkinkan verifikasi bahwa kemampuan baru yang diluncurkan di lingkungan produksi berfungsi dengan baik. Setelah personel operasional menggunakan fitur baru secara online dan mengambil tangkapan layar, mereka menambahkannya ke artikel. Operasional mengonfirmasi dokumen konten yang telah selesai dari iterasi ini, memilihnya, dan mengajukan permintaan MR (Merge Request) untuk digabungkan ke cabang utama. Manajer operasional atau administrator proyek lainnya meninjau konten dokumen yang akan diterbitkan, mengonfirmasi kebenarannya, dan kemudian memilih untuk menggabungkannya ke cabang utama. Setelah penggabungan selesai, ketika pengguna mengakses dokumen yang diterbitkan, mereka dapat melihat konten terbaru yang digabungkan ke cabang utama. ## Keunggulan Lain Selain kemampuan yang telah diperkenalkan, Apidog juga memiliki fitur-fitur berikut dalam hal penerbitan dokumen untuk membantu semua orang membangun situs dokumentasi produk yang lebih sesuai dengan kebutuhan mereka. ### 1. Atur Gaya Situs Dokumentasi Keseluruhan yang Sesuai dengan Gaya Produk/Perusahaan Anda dapat mengatur gaya keseluruhan situs dokumentasi yang diterbitkan, membuat gaya seluruh situs web lebih selaras dengan nuansa perusahaan Anda, dan menambahkan lebih banyak sumber daya terkait serta tautan konten perusahaan untuk memberikan pengalaman yang lebih baik kepada pengguna. Dokumentasi bantuan Apidog telah mengatur logonya sendiri dan beberapa tautan sumber daya terkait Apidog. Bagian kiri atas berisi logo perusahaan, bagian kanan atas berisi berbagai tautan sumber daya terkait perusahaan, dan dokumentasi API terbuka yang lebih diperhatikan oleh pengembang juga diatur dalam dokumentasi produk: ### 2. Pengalaman Penerbitan Tanpa Pemeliharaan Di Apidog, Anda hanya perlu mengklik tombol "Terbitkan" di fitur penerbitan dokumentasi untuk menerbitkan seluruh dokumentasi ke internet dengan satu klik agar dapat dibaca oleh pengguna Anda. Apidog secara resmi menyediakan domain untuk digunakan semua orang, menghemat banyak pekerjaan pemeliharaan. Tentu saja, jika Anda perlu membuat dokumentasi lebih mirip situs web perusahaan Anda sendiri, kami juga menyediakan fungsionalitas domain kustom, memungkinkan Anda menggunakan domain perusahaan Anda sendiri untuk mengakses dokumentasi. Anda juga dapat dengan mudah mengatur pencarian reguler, pencarian teks lengkap Algolia, mengintegrasikan GA, mengatur pengalihan, dan kemampuan canggih lainnya di situs dokumentasi produk yang diterbitkan dengan operasi sederhana. Konfigurasi ini tidak mengharuskan operator memiliki kemampuan rekayasa yang memadai – mereka dapat dengan mudah diatur dengan mengikuti panduan antarmuka dan dokumentasi bantuan. ### 3. Berbagai Pengaturan Ramah SEO Apidog secara otomatis menghasilkan Slug yang masuk akal untuk situs dokumentasi yang diterbitkan berdasarkan pengaturan dasar untuk memungkinkan pengguna mengakses dan membagikannya dengan lebih baik. Tentu saja, jika Anda memiliki kebutuhan SEO yang lebih canggih, Apidog juga mendukung Slug kustom, Meta Data, dan berbagai pengaturan konten lainnya untuk setiap dokumen individual. ## Kesimpulan Di atas adalah praktik spesifik penggunaan Apidog untuk pemeliharaan dokumentasi produk. Selain konten yang disebutkan di atas, kami juga dapat memelihara dokumentasi bantuan produk, dokumentasi pengembang, dan dokumentasi API dalam satu gaya dan menghubungkan semuanya, memberikan pengalaman pengguna yang lebih baik lagi. Jika situasi Anda sesuai, silakan coba praktik ini dan rekomendasikan kepada rekan kerja lainnya. Kami berharap ini dapat membawa peningkatan efisiensi dan kualitas pada pekerjaan pembangunan dokumentasi produk Anda.