Tools untuk Membuat Dokumentasi
Dokumentasi sering kali terlupakan saat proses pengembangan perangkat lunak, padahal dokumentasi berperan penting dalam penjelasan sebuah project, bagaimana cara kita bekerja dengan apps tersebut, proses pemasangan perangkat lunak tersebut hingga memudahkan kita dalam mengurangi "pain" pada saat onboarding tim baru.
Dokumentasi pun, ada beragam jenisnya. Ada yang hanya digunakan untuk memberitahu informasi mengenai
- Step by step install
- Alur Kerja Software tersebut
- Coding Styleguide
- dst
Karena itulah ada banyak sekali jenis jenis cara untuk bisa membuat dokumentasi, tergantung tujuan dari dokumentasi tersebut dan siapa yang membacanya.
Readme
Sesimple Readme di Github, teman-teman bisa menggunakan https://readme.so/ untuk memudahkan dalam membuat Readme. Readme disini bisa digunakan untuk memberikan informasi yang ringan mengenai sebuah project misalnya untuk
- Step by Step pemasangan software di local machine
- Tech Stack yang digunakan
- Folder Structure
- FAQ
- Usage
- dst
Mayoritas digunakan pada project project open source di Github. Beberapa contoh Readme.md yang cukup bagus seperti :
Storybook
Storybook adalah tools untuk membuat dokumentasi terkait dengan UI Component, misalnya ketika kita akan membuat sebuah
- Design System
- UI Kit
Selain bisa digunakan untuk membuat dokumentasi UI, kita bisa menggunakan Storybook untuk melakukan testing component UI, misalnya untuk test props dari variants component UI bekerja. Beberapa contoh penggunakan Storybook :
Docusaurus
Docusaurus adalah sebuah Site Generator dengan menggunakan ReactJS yang berfokus pada dokumentasi, sehingga saat kita menggunakan kita bisa langsung fokus pada penulisan dokumentasi produk kita. Tidak perlu mengurus Styling (kecuali bila ingin disesuaikan dengan brand perusahaan).
Ini sangat cocok bila kita gunakan untuk
- Step by Step Install
- Dokumentasi terkait penggunaan Apps / Library
- Referensi API
- dst
Docusaurus menggunakan MDX, sehingga memudahkan kita dalam melakukan format tulisan yang akan dibuat, support code highlight, component interaction.
Beberapa contoh yang menggunakan Docusaurus :
Notion
Notion adalah salah satu project management untuk menuliskan catatan catatan penting dalam sebuah ruang kerja. Alasan inilah yang membuat banyak perusahaan menggunakannya sebagai tempat untuk membuat dokumentasi di Notion yang batasannya tidak hanya pada template-template yang dimiliki Notion, namun juga komunitasnya.
Notion juga memberikan kemudahan dengan integrasi dengan Third Party yaitu
- Google Docs
- Figma
- Slack
- Jira
- Typeform
- dst
Selain itu, munculnya Notion API membuat kita bisa membuat Web berbasis Notion, misalnya Blog, dan Personal Site.
Beberapa contoh Wiki Engineering di Notion :
https://www.notion.so/templates/engineering-wiki
Custom
Kurang merasa cocok dengan tools dokumentasi yang saya sebutkan diatas? Mungkin bisa dengan membuat sendiri dokumentasinya dengan menggunakan Framework JS untuk membuat SSG (Static Site Generator).
Nextra
Menggunakan NextJS untuk membuat SSG, Nextra merupakan salah satu lib yang bisa kita gunakan karena menggunakan Tech Stack
- Typescript
- NextJS
- TailwindCSS
Menggunakan teknologi populer, akan memudahkan kita dalam mengcustom dokumentasi yang akan kita gunakan. Sayangnya, Nextra masih belum tahap rilis, atau masih beta. Sehingga bisa jadi banyak perubahan pada API-nya. Namun, Nextra sudah digunakan untuk membuat dokumentasi SWR.
Gatsby Docs Theme
Gatsby merupakan salah satu framework ReactJS yang berfokus pada SSG. Karena itu kita bisa membuat dokumentasi dengan integrasi Markdown, merubah styling sesuai dengan yang kita inginkan. Bahkan sudah banyak sekali template / Gatsby Theme untuk membuat dokumentasi :
Penggunaan tools tentu harus menyesuaikan dengan siapa pembaca dokumentasi, siapa yang bertugas menulis dokumentasi dan apa saja yang ada didokumentasi tersebut. Ini membuat orang menjadi lebih mudah untuk membaca dokumentasi tersebut, tujuan dokumentasi kan untuk memudahkan orang menggunakan apps, kalau dokumentasi tersebut susah untuk dibaca, bagaimana orang mau menggunakan dokumentasi tersebut?