Daftar isi

Jenis dokumentasi

Di bawah ini adalah uraian singkat tentang jenis-jenis kontribusi dokumentasi yang diterima di amp.dev

Tutorial pengantar

Tutorial Pengantar membantu pengembang untuk memahami gagasan umum teknologi ini. Ini akan membantu mereka memulai pengodean dan berakhir dengan proyek “Halo Dunia” (Hello World) tahap dasar yang lengkap. Tutorial Pengantar memperlihatkan cara membangun fitur penting AMP langkah demi langkah. Sandingkan tutorial Pengantar dengan sampel kode inline dan/atau sample yang dapat diunduh yang memerlukan modifikasi minimal oleh pengembang agar dapat berjalan.

contoh-contoh amp.dev:

Lakukan	Jangan Lakukan
Memberikan panduan dengan penjelasan singkat dan langkah-langkah minimal.	Terlalu menyelami nuansa proyek. Mungkin ada banyak cara untuk mencapai hasil tutorial, namun intinya bukan untuk memperlihatkan setiap rute, tetapi satu rute yang bagus.
Menyediakan lingkungan yang disederhanakan dan alat-alat penyiapan.	Menganggap pengembang telah memahami produk dan memiliki kemampuan pada tingkat pengodean.
Mempertahankan agar sampel tetap sederhana secara visual.	Membuat rumit demi gaya, kecuali jika tutorial memang tentang pembuatan gaya.
Menyediakan tangkapan layar setiap langkah dan demo yang telah jadi.	Hanya menyediakan sampel kode.
Membuat ajakan untuk bertindak. Arahkan pengembang ke hal yang seharusnya ditindaklanjuti.	Menyertakan penjelasan lebih lanjut pada contoh. Pertimbangkan untuk membuat pembahasan suatu masalah untuk panduan atau tutorial jika Anda merasa tidak ada tindak lanjut yang memadai.

Tutorial Tingkat Lanjut

Tutorial Tingkat Lanjut membantu pengembang untuk menyelesaikan suatu tugas yang spesifik. Pada tahap tutorial ini, pengembang dianggap telah sedikit memahami AMP. Tutorial ini akan memperlihatkan cara membangun pengalaman, mengintegrasikan sebuah fitur, atau menangani tugas-tugas penerapan.

contoh-contoh amp.dev:

Lakukan	Jangan Lakukan
Menyediakan instruksi langkah demi langkah dengan proyek akhir yang jelas.	Menyediakan detail yang sangat lengkap dengan konsep yang terlalu rumit.
Menyediakan sampel kode atau kode starter yang dapat diunduh. Selain itu, atur agar proyek yang sudah jadi dan lengkap dapat diunduh.	Memberikan contoh atau proses alternatif untuk mencapai hasil akhir.
Menciptakan lingkungan pasang dan pakai (PnP).	Menyediakan tautan lain untuk tutorial penyiapan. Tutorial seharusnya tidak terpisah.

Panduan Pengantar

Sebuah panduan pengantar memberikan gambaran umum tentang informasi yang relevan untuk memulai dengan AMP. Panduan ini seharusnya mengidentifikasi fitur, menjelaskan tentangnya, dan mengakhirinya dengan menyampaikan fungsinya. Panduan pengantar memperkenalkan persyaratan dasar fitur kepada pengembang tanpa mengarahkannya untuk menerapkan hal itu. Jika Anda menyediakan proses langkah demi langkah dengan sampel kode, Anda mungkin sedang menulis tutorial. Jika Anda menguraikan semua unsur program untuk sebuah komponen AMP, Anda mungkin sedang menulis dokumen referensi.

contoh-contoh amp.dev:

Lakukan	Jangan Lakukan
Mengidentifikasi apa yang akan dicakup dokumen.	Menguraikan ke dalam proses langkah demi langkah.
Memperkenalkan berbagai fitur dan konsep. Tautkan ke dokumen referensi untuk detail penggunaan tingkat lebih lanjut.	Menjelaskan dalam detail yang terlalu lengkap.
Menyediakan sampel kode dan contoh dunia nyata.	Membuat seluruh aplikasi. Sebaiknya, tautkan ke contoh atau demo, jangan berikan eksplorasi lebih jauh.
Mencantumkan penggunaan dan keterbatasan teknis.	Mencantumkan setiap penggunaan teknis yang mungkin dan cara melakukannya.

Panduan konsep

Panduan konsep membantu pengembang membangun pemahaman yang lebih mendalam tentang AMP. Panduan konsep mirip dengan peta topografis. Peta yang memperlihatkan sejumlah jalan di suatu area dan dilengkapi dengan detail, seperti perubahan ketinggian, namun tidak menjelaskan rute spesifik yang melalui medan tersebut. Jelaskan tentang sebuah fitur dan caranya berfungsi, jangan jelaskan cara membangun sebuah fitur.

contoh-contoh amp.dev:

Lakukan	Jangan Lakukan
Menyediakan semua elemen yang diperlukan untuk membangun suatu solusi kepada pengembang.	Secara aktif memandu pengembang ke keadaan akhir yang spesifik.
Membahas semua aspek area subjek.	Berfokus pada satu tugas yang spesifik.
Menyertakan alat bantu visual, seperti diagram atau tangkapan layar.	Terlalu memikirkan hal ini. Anda dapat meminta bantuan menyangkut alat bantu visual dari [kelompok kerja sosialisasi](https://github.com/ampproject/wg-outreach).
Menyediakan sampel kode dan menautkan dengan panduan-panduan lain.	Menyediakan unduhan pada proyek jadi atau menyimpang dari topik.

Dokumentasi referensi

Dokumentasi referensi mencantumkan semua elemen program untuk komponen AMP. Dokumentasi ini menyediakan informasi perilaku terperinci dan dirancang untuk pemindaian. Dokumentasi referensi harus menyertakan sampel kode unggulan dan memperlihatkan kasus-kasus penggunaan.

dokumen referensi amp.dev ada di bagian katalog komponen AMP.

Dokumentasi referensi AMP dikontribusikan untuk repositori HTML AMP.

Lakukan	Jangan Lakukan
Menggunakan bahasa yang jelas dan singkat yang menjelaskan cara kerja komponen.	Menjelaskan sebuah proses atau membangun sebuah proyek.
Struktur dengan judul, tajuk, dan subtajuk yang mudah dipindai.	Konten kelompok dengan nama-nama yang abstrak.
Menyediakan snippet kode yang memperlihatkan penggunaan komponen.	Membuat aplikasi demo lengkap.

Written by @CrystalOnScript