Anda mungkin memiliki proyek open source yang lebih baik, tetapi jika tidak memiliki dokumentasi yang baik, kemungkinan itu tidak akan pernah lepas landas. Di kantor, dokumentasi yang baik akan memungkinkan Anda untuk tidak menjawab pertanyaan yang sama. Dokumentasi juga memastikan bahwa orang dapat memahami proyek jika karyawan kunci meninggalkan perusahaan atau peran berubah. Pedoman langsung membantu memastikan integritas data.
Jika Anda perlu menulis teks yang panjang, penurunan harga adalah alternatif yang bagus untuk HTML. Terkadang sintaks penurunan harga tidak cukup. Dalam hal ini, kita dapat menggunakan HTML di dalamnya. Misalnya, elemen khusus. Karena itu, jika Anda membangun sistem desain dengan komponen web asli, mereka mudah dimasukkan dalam dokumentasi teks. Jika Anda menggunakan React (atau kerangka kerja JSX lainnya seperti Preact atau Vue), Anda dapat melakukan hal yang sama dengan MDX.
Artikel ini adalah ikhtisar luas penulisan dokumentasi dan alat pedoman. Tidak semua alat yang tercantum di sini menggunakan MDX, tetapi semakin banyak dimasukkan dalam alat dokumentasi.
Apa itu MDX?
File .mdx memiliki sintaks yang sama dengan penurunan harga, tetapi memungkinkan Anda untuk mengimpor komponen interaktif JSX dan menanamkannya dalam konten Anda. Dukungan untuk komponen Vue ada di alpha. Untuk mulai bekerja dengan MDX, cukup instal "Buat Aplikasi Bereaksi". Ada plugin untuk Next.js dan Gatsby. Versi Docusaurus berikutnya (versi 2) juga akan memiliki dukungan bawaan.
Menulis Dokumentasi dengan Docusaurus
Docusaurus menulis di Facebook. Mereka menggunakannya pada setiap proyek open source kecuali Bereaksi. Di luar perusahaan, Redux, Prettier, Gulp, dan Babel menggunakannya.
Proyek yang menggunakan Docusaurus.
Docusaurus dapat digunakan untuk menulis dokumentasi apa pun , tidak hanya untuk menggambarkan frontend. Dia memiliki Bereaksi di bawah tudungnya, tetapi untuk menggunakannya, tidak perlu mengenalnya. Dibutuhkan file Markdown Anda, sedikit keajaiban dan dokumentasi yang terstruktur dengan baik, diformat, dan mudah dibaca dengan desain yang cantik siap.
Di situs web Redux Anda dapat melihat templat Docusaurus standar
Situs yang dibuat menggunakan Docusaurus juga dapat mencakup blog berbasis penurunan harga. Prism.js segera terhubung ke penyorotan sintaksis. Terlepas dari kenyataan bahwa Docusaurus muncul relatif baru-baru ini, itu diakui sebagai alat terbaik tahun 2018 di StackShare.
Opsi pembuatan konten lainnya
Docusaurus dirancang khusus untuk membuat dokumentasi. Tentu saja, ada sejuta dan satu cara untuk membuat situs - Anda dapat menggunakan solusi Anda sendiri dalam bahasa apa pun, CMS atau menggunakan generator situs statis.
Misalnya, dokumentasi untuk Bereaksi, sistem desain IBM, Apollo, dan Ghost CMS menggunakan Gatsby - generator situs statis yang sering digunakan untuk blog. Jika Anda bekerja dengan Vue, maka VuePress adalah pilihan yang baik untuk Anda. Pilihan lain adalah menggunakan generator yang ditulis dengan Python - MkDocs. Ini terbuka dan dapat dikonfigurasi dengan satu file YAML. GitBook juga merupakan pilihan yang baik, tetapi gratis hanya untuk tim terbuka dan nirlaba. Dan Anda bisa mengunggah file mardown menggunakan gith dan bekerja dengannya di Github.
Dokumentasi Komponen: Docz, Storybook, dan Styleguidist
Panduan, desain sistem, pustaka komponen - apa pun namanya, tetapi belakangan ini menjadi sangat populer. Munculnya kerangka kerja komponen, seperti Bereaksi dan alat yang disebutkan di sini, telah memungkinkan untuk mengubahnya dari proyek sombong menjadi alat yang berguna.
Storybook, Docz dan Styleguidist - lakukan hal yang sama: tampilkan elemen interaktif dan dokumentasikan API mereka. Sebuah proyek dapat memiliki lusinan atau bahkan ratusan komponen - semuanya dengan status dan gaya yang berbeda. Jika Anda ingin komponen digunakan kembali, orang perlu tahu bahwa mereka ada. Untuk melakukan ini, cukup katalog komponen. Pedoman menyediakan ikhtisar yang dapat dicari dari semua komponen Anda. Ini membantu menjaga konsistensi visual dan menghindari pekerjaan yang berulang.
Alat-alat ini menyediakan cara yang nyaman untuk melihat berbagai negara. Mungkin sulit untuk mereproduksi setiap status komponen dalam konteks aplikasi nyata. Alih-alih mengklik aplikasi yang sebenarnya, Anda harus mengembangkan komponen terpisah. Anda dapat mensimulasikan kondisi yang sulit dijangkau (misalnya, status boot).
Bersamaan dengan demonstrasi visual dari berbagai negara bagian dan daftar properti, seringkali perlu untuk menulis deskripsi umum tentang konten - pembenaran untuk desain, studi kasus atau deskripsi hasil pengujian pengguna. Penurunan harga sangat mudah dipelajari - idealnya, pedoman harus menjadi sumber daya bersama untuk desainer dan pengembang. Docz, Styleguidist dan Storybook menawarkan cara untuk memadukan Markdown dengan komponen dengan mudah.
Docz
Sekarang Docz hanya bekerja dengan React, tetapi ada pekerjaan aktif pada dukungan untuk komponen Preact, Vue dan web. Docz adalah yang terbaru dari tiga instrumen, tetapi pada Github ia mampu mengumpulkan lebih dari 14.000 bintang. Docz mewakili dua komponen - <Playground> dan < Props > . Mereka diimpor dan digunakan dalam file .mdx .
import { Playground, Props } from "docz"; import Button from "../src/Button"; ## You can _write_ **markdown** ### You can import and use components <Button>click</Button>
Anda dapat membungkus komponen Bereaksi Anda sendiri dengan <Playground> untuk membuat analog dari CodePen atau CodeSandbox bawaan - yaitu, Anda melihat komponen Anda dan Anda dapat mengeditnya.
<Playground> <Button>click</Button> </Playground>
<Props> akan menampilkan semua properti yang tersedia untuk komponen Bereaksi ini, nilai default, dan apakah diperlukan properti.
<Props of={Button} />
Secara pribadi, saya pikir pendekatan berbasis MDX ini adalah yang paling mudah dipahami dan paling mudah untuk dikerjakan.
Jika Anda penggemar generator situs statis Gatsby, Docz menawarkan integrasi hebat.
Penjaga gaya
Seperti Docz, contoh ditulis menggunakan sintaks Markdown. Styleguidist menggunakan blok kode penurunan harga (tanda kutip tiga) dalam file .md biasa, bukan dalam MDX.
```js <Button onClick={() => console.log('clicked')>Push Me</Button>
Blok kode dalam penurunan harga biasanya hanya menunjukkan kode. Saat menggunakan Styleguidist, setiap blok kode dengan tag bahasa js , jsx atau javascript akan ditampilkan sebagai komponen Bereaksi. Seperti di Docz, kode dapat diedit - Anda dapat mengubah properti dan langsung melihat hasilnya.
Styleguidist akan secara otomatis membuat tabel properti dari deklarasi PropTypes, Flow, atau Typecript.
Styleguidist sekarang mendukung React dan Vue.
Buku cerita
Storybook memposisikan dirinya sebagai "lingkungan pengembangan untuk komponen UI." Alih-alih menulis contoh komponen dalam file Markdown atau MDX, Anda menulis cerita di dalam file Javascript. Sejarah didokumentasikan oleh keadaan spesifik komponen. Misalnya, komponen mungkin memiliki riwayat untuk kondisi boot dan status dinonaktifkan.
storiesOf('Button', module) .add('disabled', () => ( <Button disabled>lorem ipsum</Button> ))
Storybook jauh lebih rumit daripada Styleguidist dan Docz. Tetapi pada saat yang sama ini adalah opsi paling populer, di Github proyek ini memiliki lebih dari 36.000 bintang. Ini adalah proyek open source, melibatkan 657 peserta dan didampingi oleh karyawan penuh waktu. Ini digunakan oleh Airbnb, Algolia, Atlassian, Lyft dan Salesforce. Storybook mendukung lebih banyak kerangka kerja daripada pesaingnya - Bereaksi, Bereaksi Asli, Vue, Angular, Mithril, Ember, Riot, Svelte, dan HTML biasa.
Dalam rilis mendatang, akan ada chip dari Docz dan MDX akan diperkenalkan.
# Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story>
Fitur baru Storybook akan muncul secara bertahap selama beberapa bulan ke depan dan, tampaknya, ini akan menjadi langkah besar ke depan.
Ringkasan
Manfaat perpustakaan pola dipuji dalam jutaan artikel di Medium. Ketika dilakukan dengan baik, mereka membuatnya mudah untuk menciptakan produk terkait dan mempertahankan identitas. Tentu saja, tidak ada alat ini yang secara ajaib akan membuat sistem desain. Ini membutuhkan desain yang hati-hati dan desain CSS. Tetapi ketika tiba saatnya untuk membuat sistem desain tersedia untuk seluruh perusahaan, Docz, Storybook dan Styleguidist adalah pilihan bagus.
Dari penerjemah. Ini adalah pengalaman pertama saya di Habré. Jika Anda menemukan beberapa tidak akurat, atau ada saran untuk meningkatkan artikel - tulis secara pribadi.