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 :

ohmyzsh/README.md at master · ohmyzsh/ohmyzsh
🙃 A delightful community-driven (with 2,000+ contributors) framework for managing your zsh configuration. Includes 300+ optional plugins (rails, git, macOS, hub, docker, homebrew, node, php, pyth...
twin.macro/README.md at master · ben-rogerson/twin.macro
🦹‍♂️ Twin blends the magic of Tailwind with the flexibility of css-in-js (emotion, styled-components, stitches and goober) at build time. - twin.macro/README.md at master · ben-rogerson/twin.macro

Storybook

Storybook: UI component explorer for frontend developers
Storybook is an open source tool for building UI components and pages in isolation. It streamlines UI development, testing, and documentation.

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

Build optimized websites quickly, focus on your content | Docusaurus
An optimized site generator in React. Docusaurus helps you to move fast and write content. Build documentation websites, blogs, marketing pages, and more.

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

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

Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.
A new tool that blends your everyday work apps into one. It’s the all-in-one workspace for you and your team
Documentation Made Easy
Imitation is the sincerest form of flattery. 65+ Notion docs for early stage startups.

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

GitHub - shuding/nextra: The Next.js Static Site Generator
The Next.js Static Site Generator. Contribute to shuding/nextra development by creating an account on GitHub.

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.

Getting Started – SWR
SWR is a React Hooks library for data fetching. SWR first returns the data from cache (stale), then sends the fetch request (revalidate), and finally comes with the up-to-date data again.

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?

👀 Referensi :

Documentation in Software Development ► README, Flowchart, Coding style guides
In software development we create different types of documentation. Let’s tell more about the project documentation types.

Tag

Faldi

Manusia pada umumnya

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.