Dokumentasi Front-End, Panduan Gaya dan Bangkitnya MDX

Dokumentasi Front-End, Panduan Gaya dan Bangkitnya MDX

Anda dapat memiliki proyek open source terbaik di dunia tetapi, jika tidak memiliki dokumentasi yang baik, kemungkinan itu tidak akan pernah lepas landas. Di kantor, dokumentasi yang baik dapat menghemat Anda karena harus berulang kali menjawab pertanyaan yang sama. Dokumentasi memastikan bahwa orang-orang dapat mengetahui bagaimana hal-hal bekerja jika karyawan kunci memutuskan untuk meninggalkan perusahaan atau mengubah peran. Pedoman pengkodean yang terdokumentasi dengan baik membantu membawa konsistensi ke basis kode.

Jika Anda menulis teks bentuk panjang, Markdown jelas merupakan alternatif yang bagus untuk membuat HTML. Namun terkadang, sintaks Markdown tidak cukup. Selalu dimungkinkan untuk menulis HTML langsung di dalam dokumen Markdown. Ini termasuk elemen khusus sehingga, jika Anda membangun sistem desain dengan komponen web asli, mudah untuk memasukkannya ke dalam dokumentasi berbasis teks Anda. Jika Anda bekerja dengan React (atau kerangka kerja lain yang menggunakan JSX, seperti Preact atau Vue), Anda dapat melakukan hal yang sama dengan menggunakan MDX.

Artikel ini adalah tinjauan luas alat yang tersedia untuk menulis dokumentasi dan untuk panduan gaya bangunan. Tidak semua alat yang tercantum di sini menggunakan MDX tetapi semakin dimasukkan ke dalam alat dokumentasi.

Apa itu MDX?

File .mdx memiliki sintaks yang persis sama dengan file penurunan harga biasa, tetapi memungkinkan Anda mengimpor komponen JSX interaktif dan menanamkannya dalam konten Anda. Dukungan untuk komponen Vue ada di alpha. Mudah untuk menyiapkan MDX dengan Create React App. Ada plugin MDX untuk Next.js dan Gatsby. Rilis versi dua Docusaurus yang akan datang juga akan datang dengan dukungan bawaan.

Dokumentasi #Writing dengan Docusaurus
Docusaurus dibuat oleh Facebook dan digunakan oleh setiap proyek open source Facebook, selain dari React. Ini juga digunakan oleh banyak proyek open source besar di luar Facebook, termasuk Redux, Prettier, Gulp dan Babel.

Tangkapan layar logo dari berbagai kerangka kerja yang mendukung Docusaurus, termasuk React, Gulp, Jest, Babel, Redux, dan Prettier.
Proyek yang memanfaatkan Docusaurus.
Anda dapat menggunakan Docusaurus untuk mendokumentasikan apa pun - itu tidak spesifik front-end. Docusaurus menggunakan Bereaksi di bawah tenda, tetapi Anda tidak perlu tahu kerangka itu untuk memanfaatkannya. Ini akan mengambil file Penurunan harga Anda dan mengubahnya menjadi situs dokumentasi yang terstruktur dengan baik, diformat dengan baik, dan dapat dibaca, dengan desain yang bagus langsung dari kotak.

Tangkapan layar beranda dokumentasi Redux dengan tajuk Memulai Penggunaan dengan Redux.
Situs Redux menunjukkan tata letak Docusaurus yang khas
Situs yang dibuat dengan Docusaurus juga dapat menyertakan blog berbasis penurunan harga. Prism.js disertakan secara default untuk penyorotan sintaksis pengaturan nol. Meskipun relatif baru, Docusaurus telah terbukti populer, terpilih sebagai alat nomor satu baru tahun 2018 di StackShare.

Opsi #Other untuk konten tertulis

Docusaurus secara khusus melayani pembuatan dokumentasi. Tentu saja, ada sejuta dan satu cara untuk membuat situs web - sehingga Anda dapat menggulung solusi Anda sendiri dengan bahasa back-end, CMS, atau generator situs statis.

Situs dokumentasi untuk React, sistem desain IBM, Apollo dan Ghost CMS menggunakan Gatsby, misalnya - generator situs statis umum yang sering digunakan untuk blog. Jika Anda bekerja dengan kerangka kerja Vue, VuePress menjadi pilihan yang populer. MkDocs adalah generator situs statis open source untuk membuat dokumentasi, ditulis dengan Python dan dikonfigurasikan dengan satu file YAML. GitBook adalah produk berbayar populer yang gratis untuk tim sumber terbuka dan nirlaba. Jika Anda sedang membangun dokumentasi internal dan menginginkan sesuatu yang mudah, pengalaman membaca di GitHub itu sendiri tidak buruk, sehingga Anda bisa melakukan beberapa file penurunan harga dan biarkan saja.

Komponen #Documenting: Docz, Storybook dan Styleguidist

Panduan gaya, sistem desain, perpustakaan pola - apa pun yang Anda inginkan - telah menjadi bidang perhatian yang sangat populer dalam dekade terakhir. Apa yang benar-benar membuat perbedaan dalam mengubah mereka dari proyek kesombongan menjadi alat yang bermanfaat bukanlah pemusnahan pemimpin pemikiran tetapi munculnya kerangka kerja yang didorong komponen, seperti React, dan alat yang disebutkan di sini.

Storybook, Docz dan Styleguidist semuanya melakukan hal yang sama: menampilkan komponen UI interaktif dan mendokumentasikan API mereka. Sebuah proyek mungkin memiliki lusinan atau bahkan ratusan komponen untuk dilacak - semua dengan variasi ke kondisi dan gaya. Jika Anda ingin komponen digunakan kembali, orang harus tahu bahwa mereka ada. Kami membantu kemampuan menemukan ketika kami membuat katalog komponen. Panduan gaya memberikan ikhtisar yang mudah dicari dan dipindai dari semua komponen UI Anda. Ini membantu menjaga konsistensi visual dan menghindari duplikasi pekerjaan.

Alat-alat ini menyediakan cara yang nyaman untuk meninjau berbagai negara. Mungkin sulit mereproduksi setiap keadaan komponen dalam konteks aplikasi nyata. Daripada perlu mengklik melalui aplikasi yang sebenarnya, mengembangkan komponen secara terpisah dapat membantu. Status yang sulit dijangkau (seperti kondisi pemuatan, misalnya) dapat diejek.

Dan Green menulis sinopsis yang bagus tentang manfaat menggunakan Storybook, tetapi itu berlaku sama untuk Docz dan Styleguidist:

"Storybook telah membuatnya sangat mudah bagi para desainer yang berkode untuk berkolaborasi dengan para insinyur. Dengan bekerja dalam storybook, mereka tidak perlu menjalankan seluruh lingkungan (buruh pelabuhan, dll). Untuk Wave, kami memiliki banyak komponen penting yang hanya dapat dilihat di tengah-tengah proses yang berumur pendek dan memakan waktu untuk mereproduksi (yaitu layar pemuatan yang hanya menunjukkan saat pengguna sedang menyiapkan akun pembayaran mereka). Sebelum Storybook, kami tidak memiliki cara yang baik untuk mengerjakan ini komponen dan terpaksa melakukan peretasan sementara untuk membuatnya terlihat. Sekarang, dengan Storybook kami memiliki tempat yang terisolasi untuk dengan mudah mengatasinya, yang memiliki fitur bonus yaitu mudah diakses oleh desainer dan PM. Hal ini juga membuatnya sangat mudah untuk kami untuk memamerkan negara-negara ini dalam demo sprint. "

- Dan Green, Wave Financial

Selain memvisualisasikan keadaan yang berbeda berdampingan dan membuat daftar alat peraga, sering membantu untuk menulis konten tentang suatu komponen - baik menjelaskan alasan desain, kasus penggunaan, atau menggambarkan hasil pengujian pengguna. Penurunan harga cukup mudah bagi * siapa pun * untuk belajar - idealnya panduan gaya harus menjadi sumber daya bersama bagi desainer dan pengembang yang berkontribusi bagi kedua disiplin ilmu. Docz, Styleguidist dan Storybook semuanya menawarkan cara untuk memadukan Markdown dengan komponen-komponen itu sendiri.

#Docz

Saat ini, Docz adalah proyek React-only, tetapi sedang bekerja pada dukungan untuk komponen Preact, Vue dan web. Docz adalah yang terbaru dari tiga alat, tetapi sudah berjumlah lebih dari 14.000+ bintang di GitHub. Menurut saya, ini adalah solusi termudah untuk dikerjakan. Docz menyediakan dua komponen - <Playground> dan <Props>. Ini diimpor dan digunakan langsung dalam file .mdx.

import { Playground, Props } from
 "docz"; import Button from "../src/Button"; ## You can _write_
 **markdown** ### You can import and
 use components 

Anda dapat membungkus komponen Bereaksi Anda sendiri dengan <Playground> untuk membuat yang setara dengan CodePen atau CodeSandbox yang tertanam - tampilan komponen Anda di samping kode yang dapat diedit.

<Props> will show all the available props for a given React component, default values, and whether the prop is required.

Saya pribadi menemukan pendekatan berbasis MDX ini yang paling mudah dipahami dan paling mudah untuk dikerjakan.

Tangkapan layar proyek Code Sandbox memanfaatkan alat untuk mendokumentasikan kode untuk komponen Button.
Jika Anda seorang penggemar generator situs statis berbasis React, Docz menawarkan integrasi yang hebat.

Styleguidist

Sama seperti dengan Docz, contoh ditulis menggunakan sintaks Markdown. Styleguidist menggunakan blok kode Markdown (triple backticks) dalam file .md biasa daripada MDX:

```js  ```

Blok kode dalam penurunan harga biasanya hanya menunjukkan kode. Dengan Styleguidist, setiap blok kode dengan tag bahasa js, jsx atau javascript akan dirender sebagai komponen Bereaksi bersama dengan kode. Sama seperti dengan Docz, kode ini dapat diedit - Anda dapat mengubah alat peraga dan langsung melihat hasilnya.

Tangkapan layar keluaran dokumentasi untuk tombol merah muda yang dibuat dengan Styleguidist.
Styleguidist akan secara otomatis membuat tabel alat peraga baik dari deklarasi PropTypes, Flow, atau Typecript.

Tangkapan layar tabel nilai yang dihasilkan Styleguidiist untuk dokumentasi tombol merah muda, termasuk nilai yang diterimanya.
Styleguidist saat ini mendukung React dan Vue.

Storybook

Storybook memasarkan dirinya sebagai "lingkungan pengembangan untuk komponen UI." Daripada menulis contoh komponen di dalam file Markdown atau MDX, Anda menulis * cerita * di dalam file Javascript. A * story * mendokumentasikan keadaan komponen tertentu. Sebuah komponen mungkin memiliki cerita untuk status pemuatan dan kondisi dinonaktifkan, misalnya.

storiesOf('Button',
 module) .add('disabled', () =>
 (  ))

Storybook is less straightforward to use than Styleguidist and Docz. At over 36,000 GitHub stars though, it’s the most popular option. It’s an open source project with 657 contributors and a full-time maintainer. It is used by, among others, Airbnb, Algolia, Atlassian, Lyft, and Salesforce. Storybook supports more frameworks than any other offering — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte and plain HTML are all supported.

Writing documentation about components currently requires addons. In a future release, Storybook is taking inspiration from Docz and adopting MDX.

# Button Some _notes_ about your button
 written with **markdown syntax**.
   

Storybook’s new Docs feature is being rolled out incrementally over the next couple of months and looks set to be a big step forward.

Wrapping up

The benefits of pattern libraries have been extolled at nauseating length in a million Medium articles. When done well, they aid visual consistency and facilitate the creation of cohesive products. Of course, none of these tools can magic up a design system. That takes careful thought about both design and CSS. But when it comes time to communicate that system to the rest of an organization, Docz, Storybook and Styleguidist are all great options.

Share this post