Selamat siang
Sebagai salah satu pengembang proyek
Embox open-source, saya sering mendengar (terlalu sering belakangan) bahwa proyek ini menarik, tetapi karena tidak ada dokumentasi, itu tidak dapat digunakan. Kami menjawab bahwa ada beberapa jenis dokumentasi, bahwa kami selalu dapat menjawab pertanyaan, bahwa dalam kasus-kasus ekstrem, Anda dapat mencoba mencari tahu sendiri, karena proyek ini terbuka, tetapi semua ini tidak sesuai. Saya harus berurusan dengan topik yang sangat tidak menyenangkan ini untuk pengembang. Tapi tentu saja, artikelnya bukan tentang fakta bahwa dokumentasi itu “tidak menyenangkan”! Dan tentang bagaimana kami membuat proses pengembangan dokumentasi lebih nyaman. Memang, dalam proyek yang kurang lebih besar, masalah yang berkaitan dengan dokumentasi harus muncul.
Bagi mereka yang terlalu malas untuk membaca, saya akan segera mengatakan bahwa pada akhirnya kami sampai pada pengembangan dokumentasi dalam format penurunan harga. Nah, bagi mereka yang tertarik dengan detail, alasan mengapa penurunan harga, dan apa pro dan kontra dari pendekatan ini, saya meminta kucing.
Saya akan mulai dengan membenarkan relevansi topik. Tidak hanya Embox memiliki masalah dokumentasi. Misalnya, Google telah mengumumkan analog dari program Google Summer Of Code (GSOC) untuk penulis teknis
Season of Documents . Perusahaan Lab Kaspersky mengadakan
konferensi untuk penulis teknis . Dan perusahaan Parallels menerbitkan
artikel tentang pusat tentang cara menulis dokumentasi . Semua ini menunjukkan bahwa topik itu penting dan mungkin tidak mendapat perhatian.
Rangkaian artikel yang disebutkan di atas memahami isi dokumentasi yang benar, tetapi saya ingin fokus pada proses pengembangan dokumentasi, teknologi, jika Anda mau. Memang, untuk proyek open source, ciri khasnya adalah keterbukaan sebagai properti dari proses pengembangan. Dan kami ingin menciptakan proses yang akan memenuhi persyaratan proyek kami.
Penyimpangan singkat ke dalam sejarah proses pengembangan dokumentasi kami.
Setelah proyek itu berlokasi di
googlecode . Kami memiliki wiki yang lumayan, bahkan banyak yang ingat tentang itu, bertanya di mana menemukannya dan meminta untuk mentransfernya ke github, di mana proyek itu berada sekarang (atau di tempat lain yang dapat diakses). Wiki googlecode sangat berguna. Itu multibahasa dan, menurut pendapat saya, memiliki lebih banyak fitur daripada wiki di github. Tetapi kebetulan bahwa, bersama-sama dengan googlecode itu sendiri, telah tenggelam terlupakan. Wiki saat ini di github menjalankan fungsi yang ditugaskan untuk menyampaikan informasi operasional proyek dengan cukup baik, tetapi cukup sulit untuk membuat dokumentasi lengkap di platform ini.
Tentu saja, untuk proyek sumber terbuka apa pun, Anda memerlukan dokumentasi online (dapat diakses dengan cepat) secara online, peran yang dimainkan oleh wiki, dan dokumentasi lengkap yang tersedia secara offline, karena jauh lebih mudah untuk memahami esensi dan ideologi proyek. Selain itu, membuat pencarian offline pada satu dokumen, daripada halaman wiki yang berbeda, juga jauh lebih mudah.
Mungkin opsi terbaik yang saya tahu adalah
dokumentasi ARM . Yaitu, dokumentasi online, di mana ada pencarian di semua bagian, tetapi dokumen tertentu tersedia untuk diunduh dalam format pdf. Sayangnya, Embox belum mencapai tingkat ARM dalam hal kemampuan. Karena itu, kami harus melakukan versi offline secara terpisah. Untuk ini, kami menggunakan layanan
Google Documents . Nyaman karena: memungkinkan Anda mengunduh data dalam berbagai format, berkolaborasi, dan memiliki sistem kontrol versi bawaan. Kami mentransfer beberapa informasi dari wiki, mengatur struktur, karena tujuan mengembangkan versi offline adalah untuk membuat dokumentasi holistik, dan mulai mengembangkan beberapa dokumen. Tapi cukup cepat, kami mengalami masalah. Informasi sudah ketinggalan zaman, data dari wiki tidak cocok dengan data dari dokumentasi offline, dan yang paling penting, kami tidak dapat membuat dokumentasi lengkap. Ada struktur, tetapi karena tidak mungkin mendapatkan umpan balik yang layak dari pengguna, ternyata hanya pembuatnya yang dapat memahami dokumentasi. Ini tentu saja bukan masalah layanan, tetapi kenyataannya, seperti yang mereka katakan, jelas. Kami harus mencari pendekatan yang berbeda untuk masalah ini.
Kemudian kami mencoba untuk hanya mentransfer data dari wiki lama ke wiki github, tetapi bahkan kemudian kami dengan cepat mengalami masalah. Kami menemukan bahwa sebagian informasi sudah usang, sebagian belum ditambahkan, sebagian tidak jelas cara menyajikannya dalam bentuk yang mudah digunakan. Melanjutkan pencarian solusi untuk masalah, pada titik tertentu, kami bahkan mempertimbangkan untuk mengembangkan dokumentasi di TeX menggunakan repositori git, tetapi dengan cepat menyadari bahwa ini sudah terlalu banyak. Meskipun ide ini berdampak.
Kami memutuskan untuk merumuskan apa yang kami inginkan dari dokumentasi, artinya dari proses pengembangan dokumentasi, kami meninggalkan konten di luar tanda kurung:
- Dokumentasi harus disimpan dalam format teks karena seharusnya menggunakan git sebagai sistem kontrol versi
- Dokumentasi harus memiliki versi online (wiki) dan offline (dokumen terpisah, misalnya, dalam pdf)
- Dokumentasi online dan offline harus dapat dengan mudah disinkronkan.
- Dokumentasi harus terdiri dari bagian (bab) yang dapat dikembangkan atau dipelajari secara terpisah, tetapi dari mana Anda dapat menyusun dokumentasi lengkap
Tidak ada poin yang bertentangan dengan penggunaan penurunan harga, dan itu menarik karena sudah digunakan di wiki. Anda tentu saja dapat menggunakan format berbeda dan mengonversinya menjadi penurunan harga. Tetapi setelah menyusun daftar persyaratan lain, kali ini kemampuan untuk menambahkan berbagai jenis konten (gambar, teks, pemformatan), kami sampai pada kesimpulan bahwa penurunan harga cukup memuaskan semua kebutuhan kami saat ini. Dan google pertama pada topik "markdown ke pdf" menunjukkan bahwa opsi untuk mengkonversi penurunan harga ke format lain ada dan cukup populer.
Ada beberapa opsi untuk mengubah penurunan harga menjadi pdf , tetapi
pandoc sejauh ini paling populer. Utilitas ini dapat mengubah format teks apa pun menjadi format teks apa pun. Selain itu, ini adalah kantilever. Oleh karena itu, tidak hanya akrab bagi kami, tetapi juga dapat dibangun menjadi skrip untuk membuat dokumentasi dalam berbagai format.
Kami memutuskan utilitas dan mulai memikirkan pertanyaan kecil berikutnya yang harus kami selesaikan, yaitu bagaimana membuat dokumen tunggal, dan tidak banyak file pdf dengan bab berbeda yang diperoleh dari file markdown terpisah. Keinginan pertama adalah hanya untuk "menyimpan file" (untuk menggabungkan teks dari berbagai file) dalam urutan yang diinginkan, tetapi ternyata jauh lebih sederhana, pandoc itu sendiri sangat mampu bekerja dengan daftar file. Ini juga memungkinkan kami untuk memecahkan sebagian masalah yang kami butuhkan berbagai dokumen di mana konten dapat bersinggungan. Sebagai contoh, kami menghasilkan tiga dokumen dan ketiganya berisi bagian deskripsi singkat. Kami cukup daftar file ini dalam daftar untuk pandoc untuk semua dokumen.
Kami menerapkan prinsip serupa untuk menutupi halaman di mana judul dokumen terkandung, dan sebagainya. Kami baru saja membuat file dengan header untuk setiap dokumen dan memasukkannya sebagai file pertama dalam daftar sumber untuk pandoc.
Seperti yang mungkin Anda tebak, ini (daftar file yang berbeda) menyelesaikan masalah dengan multibahasa, kami hanya menentukan file dengan bahasa yang diinginkan.
Mari kita bicara sedikit lebih banyak tentang Rusia. Saat membuat pdf, pandoc menggunakan lateks sebagai backend untuk rendering, pemeriksa ejaan, dan sebagainya. Secara default, Cyrillic tidak ditampilkan dan kesalahan tentang karakter yang tidak dikenal ditampilkan. Ini diselesaikan dengan sangat sederhana, cukup tentukan "babel rusia".
--- ... header-includes: - \usepackage[russian]{babel} ---
Perlu dicatat bahwa lebih tepat untuk menunjukkan
--- ... header-includes: - \usepackage[russian, english]{babel} ---
Dan gunakan perintah lateks dalam teks
\selectlanguage{russian} \foreignlanguage{english}{ English text }
Atau
\begin{otherlanguage}{english} Text in english \end{otherlanguage}
Tetapi karena kami ingin mempertahankan "bersih" penurunan harga untuk kemungkinan transfer ke wiki, dan ternyata arahan babel sudah cukup untuk tujuan kami, kami memutuskan untuk tidak menyulitkan dan membiarkannya apa adanya.
Tentu saja, kami ingin tidak memformat dokumen, tetapi setidaknya terlihat seragam. Dan di sini lateks membantu kami lagi. Faktanya adalah karena pandoc menggunakan lateks, Anda dapat menentukan templat lateks untuknya. Ini dilakukan hanya dengan opsi --template
pandoc --template=embox_pandoc.latex ...
Setelah Anda mengompilasi templat dan menentukannya saat membuat semua dokumen, Anda mendapatkan dokumen dengan gaya yang kurang lebih seragam. "Lebih atau kurang" - karena ada beberapa masalah yang belum dapat kami pecahkan. Misalnya, pembentukan satu blok kode. Dalam penurunan harga, dimungkinkan untuk menentukan satu blok kode sehingga tidak diformat dan penyorotan sintaksis mungkin diaktifkan. Tetapi kami hanya berhasil membuat blok satu baris. Ini ternyata setelah melihat kode lateks yang dihasilkan.
Yaitu, ada kasus ketika blok yang sama ditempatkan pada dokumen yang berbeda sedikit berbeda.
Hal lain yang terkait dengan alfabet Cyrillic, yaitu penggunaan bahasa Rusia. Seperti disebutkan di atas, untuk menggunakan bahasa Rusia, ternyata cukup untuk menentukan babel Rusia di header. Tetapi kami menemukan beberapa keanehan, misalnya, tidak ada penyorotan tebal, dan keanehan pemformatan lainnya. Awalnya, kami berdosa karena fakta bahwa Rusia ditentukan dalam huruf besar, dan bukan dalam templat. Mereka mulai mempelajari masalahnya. Ternyata dengan cara yang baik Anda tidak perlu hanya menggunakan
\usepackage[russian, english]{babel}
tetapi juga
mengatur font \usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc}
Tetapi bahkan setelah melakukan ini, itu tidak mungkin untuk memperbaiki situasi. Ternyata tidak semua set font berisi semua opsi render, khususnya font kami tidak mengandung huruf tebal, miring, dan sebagainya. Karena tidak ada solusi sederhana untuk masalah ini, kami berpikir dan menunda masalah sampai waktu yang lebih baik. Yah, karena kami ingin menggunakan penurunan harga yang bersih (yaitu, tanpa menentukan perintah lateks), kami membuat template umum untuk kedua bahasa, dan indikasi tentang bahasa Rusia dimasukkan ke dalam header.
Hanya beberapa kata yang akan saya katakan tentang antarmuka aplikasi itu sendiri. Karena, seperti yang saya katakan, aplikasi konsol secara pribadi sangat akrab bagi kami dan mudah dikemas ke dalam skrip. Sebenarnya, antarmuka itu sederhana, tentu saja Anda dapat mengatur banyak opsi, tetapi untuk keperluan kami cukup menentukan templat, daftar file input dan file output.
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>
Di Internet Anda dapat menemukan bahwa untuk menghasilkan pdf (atau format output lain) Anda memerlukan jenis prosesor menggunakan opsi --pdf-engine = xelatex, tetapi secara default ini digunakan jika file output memiliki ekstensi pdf. Karena itu, kami juga tidak memerlukan ini.
Kami mengemas skrip untuk merakit dokumentasi dalam Makefile, sehingga itu akan menjadi cukup akrab. Dan sekarang, untuk mendapatkan dokumentasi Anda dapat mengatur lingkungan yang diperlukan, cukup panggil
make [en][ru]
Sebagai kesimpulan, beberapa kata tentang sistem kontrol versi. Prinsipnya bukan untuk menyulitkan (sederhanakan) kami berusaha mematuhi segalanya. Dan karena solusi paling sederhana adalah menggunakan repositori terpisah di github, maka
kami melakukannya . Kami berharap menggunakan github akan meningkatkan umpan balik pengguna. Lagipula, seperti yang Anda ketahui di github ada masalah di mana Anda dapat mendiskusikan kekurangan dan menawarkan ide dan arahan.
Proses ini diluncurkan baru-baru ini, atas permintaan banyak pekerja! Kami berhasil membuat versi cepat dan cepat versi
bahasa Inggris dan
Rusia , serta
versi pertama manual pengguna Rusia . Prosesnya sendiri terasa lebih nyaman bagi kami, itulah sebabnya kami membagikannya kepada publik.