Tools untuk Membuat Dokumentasi

Insight Apr 08, 2022

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 :

Webpack App

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 :

Dyte Docs

Real-time audio & video SDKs, ready to launch 🚀

Animations | Ionic Documentation

Animations: Web Animations API to Build and Run on Ionic Apps

Site Logo

Notion

https://www.notion.so/

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 :

List of 6 curated Gatsby Themes for Documentaion site

Informative and easy to use documentation themes for your project. Most of them created by well-known companies and feature-rich

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?