Cara Mengotomatiskan Alur Kerja Dokumentasi Untuk Pengembang

Untuk mendapatkan hasil maksimal dari tutorial ini, Anda harus terbiasa dengan: Git, GitHub dan Linux dan baris perintah.

Mengapa Anda Harus Peduli Dengan Dokumentasi Berkualitas Tinggi?

Banyak tim berjuang dengan menulis dokumentasi . Saat Anda memeriksa kerangka kerja, dokumentasi sering kali ketinggalan zaman atau tidak jelas. Hal ini dapat menyebabkan frustrasi internal ketika anggota tim mencoba menambahkan fitur, tetapi mereka tidak memahami cara kerja fitur saat ini karena dokumentasi yang buruk. Hal ini dapat menyebabkan jam kerja yang tidak produktif.

Dokumentasi yang buruk juga mengganggu pengalaman pelanggan yang baik. Menurut Jeff Lawson, penulis Ask Your Developer dan pendiri Twilio, jika Anda menjual API sebagai produk, dokumentasi adalah iklan utama bagi pemangku kepentingan teknis . IBM melakukan studi tentang pentingnya dokumentasi, dan 90% responden mengakui bahwa mereka membuat keputusan pembelian berdasarkan kualitas dokumentasi suatu produk.

Menulis dokumentasi yang baik penting untuk pengalaman pengembang dan pelanggan.

Jika Dokumentasi Sangat Penting, Lalu Mengapa Tim Teknik Mengesampingkannya?

Menulis dokumentasi dapat membuat pengembang keluar dari "aliran". Dokumentasi sering kali berada di luar basis kode utama , dan sulit untuk ditemukan dan diperbarui. Menempatkannya di spreadsheet Excel atau CMS berpemilik bukanlah hal yang aneh.

Mengotomatiskan dokumentasi dan meningkatkan alur kerja dokumentasi memperbaikinya.

Mengotomatiskan Dokumentasi Dari Tingkat Tinggi

Apa yang dimaksud dengan mengotomatisasi dokumentasi? Ini berarti mengadopsi praktik pengembangan perangkat lunak yang umum. Saat Anda mengotomatiskan dokumentasi, Anda adalah:

• menulis dokumentasi Anda di Markdown;
• menggunakan pipa continuous integration dan continuous deployment (CI/CD) untuk menjalankan tugas seperti mengoreksi kesalahan dan menerapkan pembaruan (dalam tutorial ini, kita akan menyoroti Tindakan GitHub);
• menerapkan alat seperti Vale untuk menerapkan panduan gaya dan untuk memperbaiki kesalahan tata bahasa yang umum.

Panduan Gaya

Sebelum Anda menggunakan alat seperti Vale dan GitHub Actions untuk mengotomatiskan panduan gaya, mari luangkan waktu sejenak untuk menentukan apa sebenarnya panduan gaya itu.

Anda tahu perasaan itu ketika Anda sedang menulis dokumentasi dan ada sesuatu yang tampak sedikit aneh? Penjelasan Anda tidak sesuai dengan dokumentasi lainnya, tetapi Anda tidak dapat menjelaskan mengapa mereka salah. Tulisannya menjelaskan konsepnya, tapi sepertinya tidak pas.

Ketika Anda mendapatkan perasaan ini, suara dan nada Anda mungkin mati . Menyempurnakan suara dan nada adalah cara untuk membuat tulisan terdengar kohesif bahkan jika Anda mengembangkan dokumentasi yang telah diedit oleh tim QA, teknik, dan produk. Di bawah ini adalah contoh panduan gaya dari aplikasi bus kota TAPP, diambil dari buku Strategic Writing for UX oleh Torrey Podmajersky.

TAPP adalah aplikasi transit (untuk bus dan kereta api). Header tabel mengumumkan nilai-nilai TAPP sebagai perusahaan, efisien, dapat dipercaya, dan dapat diakses. Sisi kiri tabel mencantumkan bagian berbeda yang dicakup oleh panduan gaya: konsep, kosa kata, verbositas, tata bahasa, dan tanda baca.

Bersama-sama, ini membuat panduan gaya . Header memperkenalkan nilai, dan sisi kiri tabel memperlihatkan berbagai komponen yang akan Anda temukan dalam materi tertulis apa pun: kosa kata, tata bahasa, dan tanda baca. Keunggulan dari panduan gaya ini adalah para insinyur dan copywriter akan mengetahui dengan jelas huruf besar apa yang digunakan dan tanda baca mana yang digunakan untuk mempromosikan identitas merek Tapp.

Panduan Gaya Penulisan Teknis

Tidak semua panduan gaya datang dalam tabel. Microsoft memiliki seluruh situs web yang berfungsi sebagai panduan komprehensif, mencakup semuanya mulai dari akronim hingga komunikasi bebas bias hingga chatbot. Microsoft tentu saja bukan satu-satunya perusahaan yang memiliki panduan gaya. Google juga punya.

Masalah Dengan Panduan Gaya

Panduan gaya adalah titik awal yang bagus untuk perusahaan yang serius dengan dokumentasi. Mereka memecahkan banyak kebingungan yang mungkin dimiliki pengembang tentang bagaimana tepatnya menulis tentang fitur utama yang mereka dorong.

Masalah dengan panduan gaya adalah bahwa mereka menambah gesekan pada proses penulisan. Banyak penulis, termasuk saya, tidak repot-repot berhenti menulis dan melihat panduan gaya setiap kali mereka memiliki pertanyaan. Terkadang, panduan gaya rumit dan terlalu sulit untuk dirujuk — misalnya, Panduan Gaya Microsoft memiliki panjang lebih dari seribu halaman!

Linter dan CI/CD untuk Dokumentasi

Jika Anda seorang programmer, maka Anda mungkin akrab dengan linter. Linter adalah cara ideal untuk menerapkan standar pengkodean di tim Anda. Hal yang sama berlaku dengan dokumentasi. Saat Anda membuat linter, Anda menetapkan tolok ukur kualitas untuk dokumentasi Anda. Dalam tutorial ini, kita akan menggunakan linter Vale.

Menggunakan semacam otomatisasi dokumentasi bersama linter adalah hal biasa. Ketika kami mengatakan otomatisasi dalam konteks ini, kami mengacu pada alur kerja integrasi berkelanjutan dan penerapan berkelanjutan (CI/CD). CI mengotomatisasi pembangunan dan pengujian dokumentasi . CD mengotomatiskan pelepasan kode.

Anda dapat menggunakan berbagai jenis aplikasi untuk mengimplementasikan alur kerja CI/CD. Dalam tutorial ini, kita akan menggunakan GitHub Actions untuk menjalankan linter dokumentasi kita. GitHub Actions menjalankan CI langsung di repositori GitHub, jadi tidak perlu menggunakan aplikasi pihak ketiga, seperti CircleCI atau Travis.

Terakhir, GitHub Actions adalah event-driven , yang berarti dipicu ketika sesuatu terjadi, seperti ketika seseorang menulis pull request atau masalah. Dalam contoh kami, tindakan GitHub akan terjadi ketika seseorang mendorong perubahan ke cabang utama mereka.

Tindakan GitHub

Pertama, buat repositori GitHub. Kemudian, secara lokal, buat folder dan cd ke dalamnya.

 mkdir automated-docs cd automated-docs

Setelah Anda berada di folder, inisialisasi direktori untuk Git.

 git init

Setelah Anda menginisialisasi repositori, lanjutkan untuk membuat direktori alur kerja ke folder Anda.

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

Alur kerja adalah tempat kami akan menyimpan semua tindakan GitHub kami. Setelah Anda membuat folder workflows , buat alur kerja baru. Kami akan memberi nama alur kerja ini vale.yml .

 touch vale.yml

Vale.yml adalah file YAML. Dalam file alur kerja ini, kami akan menyertakan tindakan dan pekerjaan.

Sekarang, buka vale.yml di editor teks favorit Anda.

 nano vale.yml

Salin dan tempel berikut ini ke vale.yml , dan mari membahas konteks dan sintaksnya.

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  Ini adalah nama, atau apa yang kami sebut alur kerja kami. Ini adalah string.
• on
  Ini mengontrol alur kerja dan pemicu.
• jobs
  Di sinilah kami mengatur dan mengontrol tindakan kami. Kami memilih lingkungan tempat tindakan kami akan dijalankan — biasanya merupakan taruhan yang baik untuk menggunakan Ubuntu. Dan di sinilah kita akan menambahkan tindakan kita.

GitHub memiliki panduan tentang semua sintaks dan variabel alur kerja lainnya, jika Anda penasaran.

Di bagian ini, kami memiliki:

• mempelajari apa tindakan GitHub itu,
• membuat alur kerja GitHub pertama kami,
• mengidentifikasi bagian terpenting dari file YAML alur kerja GitHub.

Selanjutnya, kita akan menyesuaikan alur kerja GitHub untuk menggunakan Vale.

Siapkan Vale di GitHub Actions File

Setelah kami menyalin file alur kerja dasar, sekarang saatnya untuk menyesuaikannya, sehingga kami dapat mulai menggunakan tindakan Vale. Hal pertama yang harus dilakukan adalah mengubah nama file YAML menjadi Docs-Linting .

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

Selanjutnya, kami ingin menjalankan tes Vale setelah seseorang mendorong perubahan mereka ke cabang utama di GitHub. Kami tidak ingin pengujian berjalan saat seseorang membuat permintaan tarik, jadi kami akan menghapus bagian file YAML tersebut.

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

Bagian jobs adalah bagian utama dari file alur kerja, dan bertanggung jawab untuk menjalankan tindakan GitHub.

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

Tindakan ini akan berjalan pada versi terbaru Ubuntu. Tindakan Checkout memeriksa repositori agar alur kerja GitHub dapat mengaksesnya.

Sekarang saatnya untuk menambahkan tindakan Vale ke alur kerja GitHub kami.

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Kami telah menamai tindakan kami Vale . Variabel using menunjukkan versi Vale mana yang akan kita implementasikan — idealnya, kita harus uses versi terbaru. Dalam variabel with , kami menyetel debug ke true .

Bagian styles memberi kita opsi untuk menambahkan panduan gaya ke Vale. Dalam contoh ini, kita akan menggunakan gaya write-good dan panduan gaya resmi Microsoft. Perlu diingat bahwa kita juga dapat menggunakan panduan gaya lainnya.

Bagian terakhir dari tindakan GitHub ini adalah env . Untuk menjalankan tindakan GitHub ini, kita perlu menyertakan token rahasia.

Ini adalah apa hasilnya akan terlihat seperti:

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Setelah Anda selesai membuat perubahan, simpan file, komit ke Git, dan dorong perubahan Anda ke GitHub.

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

Untuk rekap, di bagian ini, kami memiliki:

• memicu tindakan untuk terjadi ketika kita mendorong kode baru ke cabang main ;
• menambahkan tindakan Vale, menyetel debug ke true dan mengidentifikasi panduan gaya;
• menambahkan token GitHub;
• melakukan perubahan dan didorong ke GitHub.

Di bagian selanjutnya, kita akan membuat file konfigurasi Vale.

Menyiapkan File Konfigurasi Vale

Buka akar direktori proyek Anda, lalu touch .vale.ini . Buka .vale.ini di editor teks. Salin dan tempel berikut ini ke .vale.ini :

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
StylesPath memberikan jalur gaya Vale.
• MinAlertLevel = warning
  Tingkat peringatan minimum menunjukkan skala keparahan dalam peringatan. Pilihannya adalah suggestion , warning , dan error .
• [formats]
Markdown = markdown menetapkan format sebagai Penurunan harga.
• [*.md]
  Konfigurasi BasedOnStyles = write-good, Microsoft akan menjalankan write-good dan Microsoft style guide pada semua file Markdown yang diakhiri dengan .md .

Pengaturan ini adalah minimum. Jika Anda tertarik untuk mempelajari lebih lanjut tentang mengonfigurasi Vale, buka dokumentasi.

Ketika Anda selesai membuat perubahan, simpan file, dan komit dan dorong ke GitHub.

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

Pada bagian ini, kita telah mempelajari internal dari file konfigurasi Vale. Sekarang saatnya membuat contoh dokumentasi.

Membuat Dokumentasi dan Memicu Tindakan Vale GitHub

Sekarang saatnya untuk melihat Aksi Vale dan GitHub beraksi! Kita akan membuat file penurunan harga dan mengisinya dengan teks. Dan kita akan mendapatkan teks kita dari DeLorean Ipsum.

Buka akar proyek Anda, lalu touch getting-started.md . Setelah Anda membuat file getting-started , buka DeLorean Ipsum dan buat beberapa teks tiruan untuk dokumentasi Anda. Kemudian, kembali ke editor teks Anda dan rekatkan teks di getting-started-md .

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Simpan file, komit, dan dorong ke GitHub.

 git add getting-started.md git commit -m "first draft" git push -u origin main

Setelah Anda mendorong perubahan, pergilah ke GitHub tempat repositori Anda berada. Buka tab Actions .

Anda akan melihat semua alur kerja Anda di sisi kiri. Kami hanya memiliki satu, bernama Docs-Linting , nama yang sama yang kami masukkan ke dalam file vale.yml .

Saat kami mendorong dokumentasi ke GitHub, kami akan memicu tindakan.

Jika tindakan telah berjalan tanpa masalah, kami akan mendapatkan tanda centang hijau.

Klik "Added docs" untuk mendapatkan laporan lengkap.

Anda akan melihat bahwa kami mendapat 11 peringatan. Mari kita berurusan dengan peringatan "kata musang". Kembali ke editor teks, buka getting-started.md , dan hapus kata “tepat”.

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Simpan perubahan, komit ke Git, dan dorong versi baru file ke GitHub. Ini harus memicu tindakan GitHub .

Jika kita mengklik "Hapus kata musang", kita akan melihat bahwa kita hanya memiliki 10 peringatan sekarang, dan peringatan "kata musang" hilang. Hore!

Kami sudah selesai, dan kami telah membahas banyak hal. Di bagian ini, kami memiliki:

• menambahkan dokumentasi ke repositori Vale GitHub Actions kami,
• memicu tindakan Vale GitHub,
• mengoreksi kesalahan yang dihasilkan oleh Vale dan mendorong perubahan kembali ke GitHub.

Kesimpulan

Di dunia yang semakin terpencil, memprioritaskan dokumentasi yang baik dan alur kerja dokumentasi yang baik adalah penting. Pertama-tama Anda harus mendefinisikan apa itu "baik" dengan membuat panduan gaya. Setelah Anda mengetahui aturan dokumentasi Anda, maka inilah saatnya untuk mengotomatisasi.

Dokumentasi harus diperlakukan seperti basis kode Anda: kumpulan pekerjaan hidup yang terus-menerus diulang dan menjadi sedikit lebih baik daripada terakhir kali Anda memperbaruinya.