Belgeleme türleri
Aşağıda amp.dev üzerinde kabul edilen belgeleme katkısı türlerine dair kısa bir özet bulabilirsiniz:
Başlangıç öğreticisi
Başlangıç öğreticileri, geliştiricinin teknolojiye dair genel bir fikir edinmesine yardımcı olur. Kodlama ile başlar ve eksiksiz bir temel "Hello World" projesiyle biter. Başlangıç öğreticileri, temel bir AMP özelliğinin adım adım nasıl oluşturulduğunu gösterir. Başlangıç öğreticilerini satır için kod örnekleriyle ve/veya geliştiricinin çalıştırması için minimum müdahale gerektiren indirilebilir bir örnekle eşleştirin.
amp.dev örnekleri:
| Yapın | Yapmayın |
| Kısa açıklamalar ve asgari adımlar ile rehberlik sağlayın. | Proje nüanslarına derinlemesine dalmayın. Öğreticinin sonucuna ulaşmak için birçok yöntem olabilir, ancak amaç her rotayı değil, tek ve iyi bir rotayı göstermektir. |
| Yükleme için basitleştirilmiş bir ortam ve araçlar sağlayın. | Geliştiricinin ürünü tanıdığını ve uzman düzeyinde kodlama becerisi olduğunu varsaymayın. |
| Örneği görsel olarak basit tutun. | Öğretici stil hakkında olmadığı müddetçe sırf stil için işlemi karmaşıklaştırmayın. |
| Her adımın ve bitmiş demonun bir ekran görüntüsünü sağlayın. | Sadece kod örnekleri vermeyin. |
| Bir eylem çağrısı oluşturun. Geliştiriciyi takip etmesi gerekenler konusunda yönlendirin. | Örneği daha fazla açıklamayla karıştırmayın. Yeterince takip materyali olmadığını düşünüyorsanız öğretici veya kılavuz için bir sorun bildirimi açmayı düşünebilirsiniz. |
Gelişmiş öğretici
Gelişmiş öğreticiler, geliştiricilerin belirli bir görevi başarmasına yardımcı olur. Geliştiricinin AMP'yi biraz bildiğini varsayar. Bir deneyimin nasıl oluşturulacağını, özelliğin nasıl entegre edileceğini veya uygulama görevlerinin nasıl ele alınacağını göstermelidir.
amp.dev örnekleri:
- AMP sayfalarınız için temel analizler nasıl yapılandırılır
- amp-script ile AMP sayfalarınıza özel JavaScript ekleyin
- AMP sitenizi PWA'ya dönüştürün
| Yapın | Yapmayın |
| Net bir son proje ile adım adım talimatlar sağlayın. | Kapsamlı ayrıntılar vermeyin ve kavramları gereğinden fazla derinlemesine açıklamayın. |
| Kod örnekleri veya indirilebilir başlangıç kodu sağlayın. Ayrıca, nihai ve eksiksiz projeyi indirilebilir hale getirin. | Nihai sonuca ulaşmak için alternatif örnekler veya süreçler sunmayın. |
| Bir tak ve çalıştır ortamı oluşturun. | Bir yükleme öğreticisine dış bağlantı vermeyin. Öğreticiler kendi içinde kapsamlı olmalıdır. |
Giriş kılavuzu
Bir giriş kılavuzu, AMP'yi kullanmaya başlamak için ilgili bilgilere genel bir bakış sunar. Özelliği tanımlamalı, ne olduğunu açıklamalı ve ne yaptığı ile bitmelidir. Giriş kılavuzları, geliştiriciye özelliğin temel gerekliliklerini tanıtır ancak onu bunları uygulamaya yönlendirmez. Kod örnekleri ile adım adım ilerliyorsanız, muhtemelen bir öğretici yazıyorsunuzdur. Bir AMP bileşeni için tüm programlı öğeleri özetliyorsanız, muhtemelen bir referans belgesi yazıyorsunuzdur.
amp.dev örnekleri:
| Yapın | Yapmayın |
| Belgenin neleri kapsayacağını belirleyin. | Adım adım aşamalara bölmeyin. |
| Özellikleri ve kavramları tanıtın. Gelişmiş kullanım ayrıntıları için referans belgelerine bağlantı verin. | Kapsamlı ayrıntılarla açıklama yapmayın. |
| Kod örnekleri ve gerçek dünyadan örnekler verin. | Bir uygulamanın tamamını oluşturmayın. Bunun yerine daha fazla araştırma için örneklere veya demolara bağlantı verin. |
| Teknik kullanımları ve kısıtlamaları listeleyin. | Olası her teknik kullanımı ve her birinin nasıl yapıldığını listelemeyin. |
Konsept kılavuzu
Konsept kılavuzları, geliştiricilerin AMP hakkında daha derin bir kavrayış geliştirmelerine yardımcı olur. Konsept kılavuzu topografik harita gibidir. Yükseklik değişiklikleri gibi ayrıntılarla bölgedeki çeşitli yolları gösterir, ancak arazide belirli bir rotanın tercih edilmesini tavsiye etmez. Bir özelliğin nasıl oluşturulacağını değil, ne olduğunu ve nasıl bir işlev gördüğünü açıklayın.
amp.dev örnekleri:
| Yapın | Yapmayın |
| Geliştiriciye, bir çözüm oluşturmak için gereken tüm öğeleri sağlayın. | Geliştiriciyi aktif olarak belirli bir son duruma yönlendirmeyin. |
| Konu alanlarının tüm yönlerini ele alın. | Belirli bir göreve odaklanmayın. |
| Diyagramlar veya ekran görüntüleri gibi görsel yardımlar ekleyin. | Üzerine çok düşünmeyin, [yardım çalışma grubu]'ndan (https://github.com/ampproject/wg-outreach) görsel yardım materyalleri konusunda yardım isteyebilirsiniz. |
| Kod örnekleri sağlayın ve diğer kılavuzlara bağlantı verin. | Tamamlanmış bir projeye indirme bağlantısı vermeyin veya konudan sapmayın. |
Referans belgeleme
Referans belgeleme, bir AMP bileşeni için tüm programlı elemanları listeler. Ayrıntılı davranış bilgisi sağlar ve tarama için tasarlanmıştır. Referans belgeleme kod örneklerini içermeli ve kullanım örneklerini göstermelidir.
amp.dev referans belgeleri AMP bileşen kataloğu altında bulunur.
| Yapın | Yapmayın |
| Bileşenin nasıl çalıştığını açıklayan kısa ve öz bir dil kullanın. | Bir süreci açıklamayın veya bir proje oluşturmayın. |
| Taranması kolay ana başlıklar, bölüm başlıkları ve alt başlıklar içeren bir yapı kullanın | İçeriği soyut isimler altında gruplandırmayın. |
| Bileşen kullanımını gösteren kod parçacıkları sağlayın. | Tam demo uygulamaları oluşturmayın. |
-