Unlimited Wordpress themes, plugins, graphics & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Web Design
  2. Documentation
Webdesign

Mendokumentasikan Proyekmu dengan Daux.io

by
Length:LongLanguages:

Indonesian (Bahasa Indonesia) translation by Husain Ali Yahya (you can also view the original English article)

Final product image
What You'll Be Creating

Mendokumentasikan proyek bisa menjadi sebuah kesulitan, namun harus-nya tidak begitu.  Ada beberapa alat di luar sana untuk menyelesaikannya- saya sering menggunakan Daux.io karena fleksibilitasnya.

Pada artikel ini, saya akan menunjukkan padamu kenapa kita harus membuat dokumentasi, dan cara menggunakan Daux.io untuk membuat proyekmu menjadi lebih baik.

Kenapa Dokumentasi Diperlukan

Menulis dokumentasi untuk proyekmu bisa jadi hal terpenting untuk kamu lakukan. Alasan ini sering diabaikan oleh proyek berbasis situs adalah karena tidak banyak hal yang dipertaruhkan.

Ambil Boeing 787 sebagai contoh. Produk ini memiliki dokumentasi luas yang menjaga setiap aspek mulai dari desain hingga pemeliharaan. Bahkan ada sekitar 150 halaman dokumentasi dengan 787 karakteristik yang perlu dipertimbangkan saat membangun bandara.

Kenapa sebuah pesawat memerlukan dokumentasi yang luas sementara situs tidak?

Saya percaya ada tiga alasan utama:

  • Ada banyak uang yang dilibatkan.
  • Alasan keamanan.
  • Masalah skala

Situs jarang memiliki pertimbangan keamanan, namun seiring banyak uang yang dikeluarkan, kamu bisa yakin bahwa dokumentasi akan muncul. Semua proyek besar seperti Twitter dan Facebook memiliki jumlah informasi yang mengejutkan bagi pengembang, baik di rumah maupun pihak ketiga. 

Situs yang bisa menghasilkan banyak pendapatan juga memilih untuk membuat dokumentasi yang bagus. Ide-nya adalah jika ada sesuatu yang perlu diubah oleh siapapun. Dia bisa mengacu ke dokumentasi dan situs-nya pun tidak akan kehilangan banyak uang.

Apakah ini berarti kamu bisa melupakan dokumentasi untuk proyek yang lebih kecil? Tentu saja iya, tapi pertanaannya adalah; kenapa?

Keuntungan dari Dokumentasi

Dokumentasi menyediakan bingkai umum dari referensi sebuah proyek. Keuntungannya cukup jelas ketika bekerja dalam tim. Namun ini seriing diabaikan ketika seseorang bekerja sendiri.

Jika kamu hidup dari membuat situs, kemungkinannya setidaknya kamu akan membuat beberapa dalam setahun. Akankah kamu ingat cara sebuah situs yang kamu buat di bulan Januari membuat konten auto-tweet-nya saat kamu melihatnya kembali pada Agustus? Bagaiamana jika sebuah perusahaan menanyakanmu untuk memberikan sebuah proyek ke pengembang lainnya? Kamu mungkin akan menghabiskan satu jam tiap pagi untuk menjawab pertanyaan mengenai kode-mu bulan depannya.

Bahkan coder paling konsisten-pun tidaklah konsisten. Seiring kita berkembang dan belajar kita cenderung merubah cara kerja ktia. Mungkin kamu mulai menggunakan alat seperti Gulp ke dalam alur kerja, mungkin kamu mulai menggunkan PHP berorientasi objek.

Dokumentasi juga bisa menjelaskan situasi yang tidak jelas di kode itu sendiri. Kamu mungkin telah memilih sebuah sub-par secara sengaja, alasannya karena kamu diminta untuk membuat sesuatu secara cepat sehingga itu dibenarkan. Ini bisa ditambahkan ke dokumentasi, mungkin sebagai tugas untuk diperbaharui nanti.

Mendokumentasikan dengan Daux.io

Daux.io mungkin menakutkan bagi beberapa orang pada awalnya karena dia bukanlah sebuah HTML sederhana, dan hanya bisa di pratijau menggunakan sebuah server. Namun, mengatur itu semua cukup mudah dan ketika kamu melewatinya, penggunaannya mudah dan fleksibel.

Memulai Daux.io

Cara termudah untuk mendapatkan Daux.io adalah mengunduhnya dari Github. Kamu bisa mengunduh paketnya menggunakan tombol Download ZIP di sisi kanan.  Jika kamu pengguna Github berpengalaman kamu bisa mengkloning-nya, atau kamu bahkan bisa mengambilnya dari Packagist melalui composer.

Jika kamu mengunduh dari Github. PAda akhirnya kamu akan memiliki folder bernama "daux-io-master".

Ganti namanya ke "documentation" dan pindahkan ke desktop-mu demi kemudahan. Untuk menulis dokumentasi-mu kamu sebenarnya tidak membutuhkan apapun. Kamu bisa mengubah berkas Markdown di editor apapun dan menggunakan sebuah perintah untuk mengonversi-nya semua ke HTML agar mudah dibagi. Namun, akan jadi bagus untuk mempratinjau pekerjaan kita seiring berjalan. Jadi kita akan melakukan beberapa persiapan untuknya.

Mempratinjau Dokumentasi

Untuk mempratinjau dokumen kita akan membutuhkan sebuah server. Untungnya, semuanya telah disediakan di dalam folder proyek Daux.io, kita hanya perlu prasyarat-nya untuk menjalankan server: npm dan Grunt.

Memasang nom dan Grunt

Cara termudah untuk mendapatkan npm (Node Package Manager) adalah dengan memasang Node. Pegi ke situs Node dan unduh installer-nya. Setela hterpasang kamu harus bisa menggunakan perintah npm di terminal (di Linux/ OS X) atau di command prompt (Windows)

Catatan singkat: Saya akan mengacu ke command prompt di Windows dan teriman di Linux/OS X dengan kata yang sama: terminal.

Hal selanjtunya yang kamu butuhkan adalah Grunt. Grunt sebenarnya dipasang melalui npm, jadi jika kamu telah menyelesaikan langkah terakhir ini akan menjadi sangat sederhana. Buka terminal dan ketik perintahy berikut:

Sekarang kamu memiliki peralatan dasar untuk memulai. Jika kamu baru dengan npm. Saya sangat menayankan kamu belajar lebih tentangnya. Dia mengizinkan kamu untuk memasang perkakas dengan liebh mudahdan kamu tidak perlu mengetahui Node.js untuk menggunakan npm (seperti Grunt).

Semuanya hingga titik ini hanya diperlukan jika kamu belum memiliki kedua alat tersebut terpasang. Tidak peduli berapa banyak contoh dokumentasi Daux.io yang kamu punya, kamu tidak perlu melakukan ini lagi.

Tips: Pelajari lebih banyak tentang command line tools dengan mengikuti seri pemula The Command Line for Web Design oleh Kezz Bracey.

Pengguna Windows: Memasang PHP

Tahap ini hanya untuk pengguna Windows. OS X dan hampir semua Linux hadir dengan PHP telah terpasang jadi jika kamu menggunakannya kamu bisa melewati bagian ini. Namun sayangnnya, memasang PHP command line di windows cukup rumit, seperti ini ini caranya.

Pergi ke halaman unduh PHP dan ambil versi PHP yang kamu inginkan. Saya menggunakan "VC11 x86 Non Thread Safe" saat uji coba. Sata telah mengunduh dan mengambil berkas ini ke folder akar, C/ dan menamai foldernya "php". Pada akhir dari prosesnya kamu harus memiliki folder bernama "php" di direktori utama C:/, foldernya harus mengandung berkas "php.exe" di suatu tempat.

Selanjutnya, kita akan memastikan bahwa PHP command bisa dijalankan dari manapun. Di Windows 7, cara termudahnya adalah dengan pergi menu start, klik kanan di Computer dan pilih Properties.  Klik Advanced System Settings di sidebar kiri. Klik tab Advanced lalu klik tombol Environment Variables di bawah.

Editing path on Windows

Kamu perlu mengklik path di panel atas dan klik edit. Pada akhir dari nilai tambahkan sebuah folder referensi baru, sesuatu sepert: "C:\Users\Dani\environment". Ini harus menjadi folder di dalam folder pengguna-mu sendiri. SEtelah selesai, simpan semuanya dan buat folder ini. (Jika kamu menggunakan versi Windows berbeda lihat Computerhope, dia mendaftar caranya di aneka versi)

Di dalam folder ini buat sebuah folder bernama "phppath.cmd" Edit berkas ini menggunakan text editor apapun dan tambahkan konten berikut:

Setelah selesai, bernavigasilah ke folder ini melalui command prompt dengan mengetik cd %userprofile%/environment dan jalankan perintah berikut: phppath.

Akhirnya, tutup command prompt dan buka lagi, php-nya akan tersedia secara global. Sekali lagi, ini hanya perlu dilakukan sekali, dan hanya pada Windows.

Mengatur Daux.io

Masih di terminal-mu, bernavigasilah ke folder proyek. Ingat, ini harus di desktop pada tahap ini. Di Windows kamu bisa menggunakan perintah berikut untuk pergi ke folder proyek.

Di OS X, kamu bisa menggunakan perintah berikut:

Perintah pertama yang perlu kamu keluarkan adalah npm install. Setelah selesai, jalankan npm update untuk memastikan semua nya baru. Perintah ini memperharui dan memasang semua dependencies dari Daux.io. Kamu harus melakukannya untuk tiap contoh Daux yang kamu miliki.

Menjalankan Pratinjau

Ktia akhirnya siap mempratinjau dokumentasi kita. Sekarang adalah masalah satu perintah, yang perlu kamu lakukan adalah mengetik grunt di terminal (pastikan kamu di folder dokumentasi saat mengeluarkan perintah).

Setelah beberapa detik, kamu harusnya mendapatkan sesuatu seperti ini:

Running Grunt with Dauxio

Ini berarti server-nya berjalan, sebuah tab baru mungkin telah terbuka di browser-mu. Jika tidak, perhatikan IP yang ditunjukkan di "Listening on" pada terminal dan masukkan dia ke browser-mu. Contohnya milik saya adalaj "127.0.0.1:8085"

Catatan: Dalam beberapa kasus tab terbuka namun menunjukan "no page found" atau error lainnya. Pada kasus ini muat ulang tab setelah beberapa detik, server-nya mungkin butuh waktu lebih untuk inisialisasi.

Kamu harusnya melihat dokumentasi bawaan yang disediakan pada browser.  Yang kamu lihat adalah ad-hoc dari berkas dokumentasi Markdown. Sekarang kamu bisa melihat apa yang akan kita lakukan, mari perhatikan cara menulis dokumentasi.

Menulis Dokumentasi

Di dalam folder "documentation" kamu seharusnya melihat folder "docs". Dia mengandung dokumentasimu yang sesungguhnya, yang lainnya adalah untuk Daux.io melakakukan sihirnya. Daux.io menggunakan konvensi nama spesifik untuk memberimu kontrol penuh ke pengaturan halaman.

Tiap benda di halaman ini harus dimulai dengan angka dan garis bawah. Semakin tinggi angkanya, semakin rendah halamanyadi dokumentasi. Jika kamu membutuhkan satu halaman membuat berkas Markdown (misalnya 04_Updating_Plugins), jika kamu membutuhkan struktur halaman hirarki buat sebuah folder (misalnya: 05_Code_Styling).

Teks setelah angkanya meentukan nama dari halaman di dokumentasinya. Contoh saya sebelumnya akan menjadi "Updating Plugiins" dan "Code Styling". Pastikan hanya menggunakan karakter alfanumerik dan gars bawah. Garis barah akan dikonversi ke spasi.

Folder names and sections in Dauxio

Dari sini dimulai pelayaran yang halus. Semua yang perlu lakukan adalah mengubah berkasmu di Markdown Style. Jika kamu tidak familiar dengan markdown perhatikan Markdown Cheatsheet. Pada dasarnya dia adalah cara untuk menandai teks (mengindikasikan headings, tautan, gambar dan lainnya) tanpa kode HTML

Jika kamu membuat bagian dengan sub-pages yang menggunakan sebuah folder. Kamu bisa menspesifikasikan sub-pages dengan  cara yang sama seperti sebelumnya. Di dalam fodler yang terbentuk buat berkas yang memulai nama berkas dengan sebuah angka (yang memberikan halaman urutannya) dan nama yang ingin ditampilkan.

Landing PAges

Satu hal lain yang Daux.io izinkan untuk dilakukan adalah membuat landing pages untuk sections. Seluruh dokumentasimu akan mendapat sebuah landing page jika kamu membuat sebuah "_index.md" berkas. Perhatikan pada contoh bawaan untuk memahami formatting-nya.

Dauxio landing page

Tiap section juga bisa memiliki sebuah landing page. Jika sebuah section tidak memiliki landing page. top level menu item-nya tidak akan mengklik kemanapun, dia hanya akan terbuka ke daftar sub-section. Jika kamu ingin top-leven entry memiliki halamannya sendiri, buat sebuah berkas "index.md" di dalam folder untuk section-nya.

Mengatur Banyak Dokumentasi

Beberapa proyek bisa membutuhkan beberapa dokumentasi. Sebuah situs boleh menjamin sebuah end-user documentation dan sebuah dokumentasi pengembang yang akan memiliki konten yang berbeda.

Salah satu cara untuk mengatur kebutuhkan banyak dokumentasi adalah dengan membuat banyak contoh dari Daux.io. Namun ini akan membuatmu menjalankan server secara terpisah dan mengatur beberapa hal lagi. Untungnya ada cara yang lebih baik!

Perhatikan berkas "global.json" di folder dokumentasi utama. Jika kamu membukanya dengan text editor kamu akan meliaht parameter docs_directory di atur ke docs. Buat salinan dari direktori docs, namai dia "user_docs" dan tambahkan beberapa berkas contoh padanya untuk bisa membedakannya dengan dokumentasi original.

Sekarang ganting parameter docs_directory ke user_docs dan muat ulang dokumentasi di browser-mu. Sekarang kamu melihat konten dari folder baru. Ini membuat perpindahan antar dokumentasi menjadi lebih mudah tanpa harus memulai ulang server dan menggunakan contoh Daux.io lainnya.

Menghasilkan Dokumentasi Akhir

Tentu saja pada akhirnya kita harus membagikan dokumentasi kita. Ini paling baik dilakukan dalam bentuk HTML dan Daux.io memilikinya untuk kita! Di terminal, saat kamu di direktori utama dokumentasi, jalankan perintah berikut:

Ini akan membuat sebuah folder "statis" dengan semua berkas dan aset HTML yang dibutuhkan untuk melihat dokumentasi. Kamu bisa men-zip foldernya dan mengirimnya ke seseorang atau mengunggahnya ke server dan menautkannya.

Pengaturan Proyek Lanjutan

Ada banyak yang bisa kamu kontrol melalui berkas "default.json" . Pada dasarnya akan ada tautan Made by Todaymade di sidebar dengan beberapa tautan Twitter yang tidak kamu butuhkan atau ingin dikostumisasi di proyekmu. Halaman utama Daux.io mendaftar opsi-opsi yang bisa kamu gunakan di bawah "Konfigurasi" halaman. atau cukup mengacu ke berkas "default.json" .

Kamu bisa menggunakan "twitter": ["yourtwittername"] untuk menambahkan tautan Twiitter-mu sendiri sebagai contohnya. Tautan bisa diatur dengan parameter links, ini cara untuk menambah beberapa.

Kamu bisa menemukan semua opsi di halaman utama Daux.io. Ini contoh berkas penuh dari "default.json" untuk sebuah proyek khayalan.

Kesimpulan

Mengatur Daux.io bisa terlihat menakutkan pada awalnya, tapi ini tidak sepenajng itu, terutama pada Mac/Linux dimana hampir semuanya sudah terpasang. Jika kamu tidak terbiasa dengan terminal dan server lokal mungkin akan membutuhkan sedikit waktu hingga terbiasa dengan lingkungannya.

Saat kamu telah menggunakan Daux.io kamu akan menyadari bawah dia mudah untuk digunakan, fleksibel dan mudah untuk diperlihara. Proyek, Klien, dan rekan kerja dari pengguna akhir proyekmu akan berterima kasih pada usahamu dan semoga saja waktu untuk memelihara proyeknya akan berkurangan.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.