Aracılığıyla paylaş

Belge yönergeleri — MRTK2

  • Makale
MRTK

Bu belgede, Karma Gerçeklik Toolkit (MRTK) için belge yönergeleri ve standartları özetlenmiştir. Bu, belge yazma ve oluşturmanın teknik yönlerine giriş sağlar, yaygın tuzakları vurgular ve önerilen yazma stilini açıklar.

Sayfanın kendisi örnek olarak görev yapması gerekir, bu nedenle belgelerin amaçlanan stilini ve en yaygın işaretleme özelliklerini kullanır.

İşlevsellik ve işaretleme

Bu bölümde sık ihtiyaç duyulan özellikler açıklanmaktadır. Nasıl çalıştıklarını görmek için sayfanın kaynak koduna bakın.

  1. Numaralandırılmış listeler
    1. En az 3 boşlukla iç içe yerleştirilmiş numaralandırılmış listeler
    2. Koddaki gerçek sayı ilgisizdir; ayrıştırma, doğru öğe numarasını ayarlama işlemini gerçekleştirir.
  • Madde işareti noktası listeleri
    • İç içe madde işareti listeleri
  • **Çift yıldız** ile kalın metin
  • _underscore_ veya *tek yıldız* içeren italik metin
  • 'Ters alıntıları kullanma' cümlesi içindeki metin highlighted as code
  • Belge sayfalarının bağlantıları MRTK belge yönergeleri
  • Sayfa içindeki tutturuculara bağlantılar; yer işaretleri boşluklar tirelerle değiştirilerek ve küçük harfe dönüştürülerek oluşturulur

Kod örnekleri için üç '' arka noktası olan blokları kullanırız ve söz dizimi vurgulama dili olarak csharp değerini belirtiriz:

int SampleFunction(int i)
{
   return i + 42;
}

Tümce use a single backtickiçinde koddan bahsederken.

TODO'lar

Zaman içinde bu TODO'lar (kod TOTO'ları gibi) birikme eğiliminde olduğundan ve bunların nasıl güncelleştirilmesi gerektiği ve neden kaybolduğu hakkında bilgi edindiğinden, belgelerde TODO'ları kullanmaktan kaçının.

ToDO eklemek kesinlikle gerekliyse şu adımları izleyin:

  1. Github'da TODO'yu destekleyen bağlamı açıklayan yeni bir sorun oluşturun ve başka bir katkıda bulunanın TODO'yu anlayıp ele alabilmesi için yeterli arka plan sağlayın.
  2. Belgelerde yapılacaklar dosyasındaki sorun URL'sine başvurun.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Sorunla ilgili kısa bir bulanıklık -->

Vurgulanan bölümler

Okuyucunun > belirli noktalarını vurgulamak için [! NOT] , > [! UYARI] ve > [! ÖNEMLİ] aşağıdaki stilleri oluşturmak için. Notların genel noktalar ve uyarı/önemli noktalar için yalnızca özel ilgili durumlar için kullanılması önerilir.

Not

Not örneği

Uyarı

Uyarı örneği

Önemli

Önemli bir açıklama örneği

Sayfa düzeni

Giriş

Ana bölüm başlığından hemen sonraki bölüm, bölümün ne hakkında olduğu hakkında kısa bir giriş niteliğinde olmalıdır. Bunu çok uzun yapma, bunun yerine alt başlıklar ekleyin. Bunlar bölümlere bağlanmaya olanak sağlar ve yer işareti olarak kaydedilebilir.

Ana gövde

Kalanları yapılandırmak için iki düzeyli ve üç düzeyli başlıklar kullanın.

Mini Bölümler

Dikkat çekmesi gereken bloklar için kalın bir metin satırı kullanın. Bunu bir noktada dört düzeyli başlıklarla değiştirebiliriz.

'Ayrıca bkz. ' bölümü

Sayfaların çoğu Ayrıca Bkz. adlı bir bölümle bitmelidir. Bu bölüm, bu konuyla ilgili sayfaların bağlantılarının madde işaretli bir listesidir. Bu bağlantılar uygun olduğunda sayfa metninde de görünebilir, ancak bu gerekli değildir. Benzer şekilde, sayfa metni ana konu ile ilgili olmayan sayfaların bağlantılarını içerebilir; bunlar Ayrıca Bkz listesine dahil edilmemelidir. Bağlantı seçimine örnek olarak bu sayfanın ''Ayrıca bkz. '' bölümüne bakın.

İçindekiler Tablosu (İçindekiler)

İçindekiler dosyaları, MRTK github.io belgelerindeki gezinti çubuklarını oluşturmak için kullanılır. Her yeni belge dosyası eklendiğinde, belge klasörünün toc.yml dosyalarından birinde bu dosya için bir girdi olduğundan emin olun. Geliştirici belgelerinin gezintisinde yalnızca içindekiler dosyalarında listelenen makaleler gösterilir. Belge klasöründeki her alt klasör için, gezintinin ilgili bölümüne alt bölüm olarak eklemek üzere var olan herhangi bir içindekiler dosyasına bağlanabilen bir içindekiler tablosu dosyası olabilir.

Stil

Yazma stili

Genel kural: Profesyonel görünmeye çalışın. Bu genellikle "konuşma tonu" kullanmaktan kaçınmak anlamına gelir. Ayrıca hiperbole ve sansasyonellikten kaçınmaya çalışın.

  1. Fazla komik olmaya çalışmayın.
  2. Asla 'I' yazma
  3. "Biz" demekten kaçının. Bunun yerine genellikle 'MRTK' kullanılarak kolayca yeniden ifade edilebilir. Örnek: "Bu özelliği destekliyoruz" -> "MRTK bu özelliği destekliyor" veya "aşağıdaki özellikler destekleniyor ...".
  4. Benzer şekilde, 'siz'den kaçınmaya çalışın. Örnek: "Bu basit değişiklikle gölgelendiriciniz yapılandırılabilir hale gelir!" -> "Gölgelendiriciler çok az çabayla yapılandırılabilir hale getirilebilir."
  5. 'Özensiz ifadeler' kullanmayın.
  6. Aşırı heyecanlı görünmekten kaçının, hiçbir şey satmamıza gerek yok.
  7. Benzer şekilde, aşırı dramatik olmaktan kaçının. Ünlem işaretleri nadiren gereklidir.

Büyük Harf Kullanımı

  • Başlıklar için Tümce büyük/küçük harflerini kullanın. Ie. ilk harfi ve adları büyük harfle yazabilirsiniz, ancak başka bir şey yoktur.
  • Diğer her şey için normal İngilizce kullanın. Bu, bu bağlamda özel bir anlam taşısalar bile rastgele sözcükleri büyük harfe çevirmeyin anlamına gelir. Belirli sözcükleri vurgulamak için italik metni tercih edin, aşağıya bakın.
  • Bir bağlantı bir cümleye eklendiğinde (tercih edilen yöntemdir), standart bölüm adı her zaman büyük harfler kullanır ve böylece metnin içinde rastgele büyük harfe çevirme kuralına son verir. Bu nedenle büyük/küçük harf kullanımını düzeltmek için özel bir bağlantı adı kullanın. Örneğin, sınır denetimi belgelerinin bağlantısı aşağıda verilmiştir.
  • Unity gibi adları büyük harfe çevirme.
  • Unity düzenleyicisini yazarken "düzenleyiciyi" büyük harfe çevirmeyin.

Vurgulama ve vurgulama

Sözcükleri vurgulamanın veya vurgulamanın iki yolu vardır; bu sözcükleri kalın veya italik hale getirir. Kalın metnin etkisi, kalın metnin dışarıda kalmalarıdır ve bu nedenle bir metin parçasını kaydırırken ve hatta bir sayfanın üzerinde kaydırırken kolayca fark edilebilir. Kalın, insanların hatırlaması gereken tümcecikleri vurgulamak için harika bir özelliktir. Ancak, genellikle dikkat dağıtıcı olduğundan kalın metinleri nadiren kullanın.

Genellikle, mantıksal olarak bir araya gelen bir şeyi "gruplandırmak" veya özel bir anlamı olduğundan belirli bir terimi vurgulamak ister. Bu tür şeylerin genel metinden öne çıkması gerekmez. Bir şeyi vurgulamak için italik metni basit bir yöntem olarak kullanın.

Benzer şekilde, metinde bir dosya adı, yol veya menü girdisi belirtildiğinde, dikkatinizi dağıtmadan mantıksal olarak gruplandırmak için italik yapmayı tercih eder.

Genel olarak, gereksiz metin vurgulamalarından kaçınmaya çalışın. Özel terimler, okuyucunun farkında olmasını sağlamak için bir kez vurgulanabilir, artık hiçbir amaca hizmet etmediğinde ve yalnızca dikkat dağıttığında bu tür vurgulamaları metin boyunca tekrarlamaz.

Menü girdilerinden bahsetme

Kullanıcının tıklaması gereken bir menü girdisinden bahsederken geçerli kural şudur: Project > Files > Create > Leaf

Diğer sayfalara mümkün olduğunca çok yararlı bağlantı ekleyin, ancak her bağlantı yalnızca bir kez. Bir okuyucunun sayfadaki her bağlantıya tıklayacağını ve aynı sayfa 20 kez açılırsa ne kadar can sıkıcı olacağını düşünün.

Tümceye eklenmiş bağlantıları tercih edin:

  • BAD: Yönergeler yararlıdır. Ayrıntılar için bu bölüme bakın.
  • İYİ: Yönergeler yararlıdır.

Dış bağlantılardan kaçının; bunlar eski olabilir veya telif hakkıyla korunan içerik içerebilir.

Bağlantı eklerken, ayrıca Bkz. bölümünde de listelenip listelenmemesi gerektiğini göz önünde bulundurun. Benzer şekilde, yeni sayfanın bağlantısının bağlı sayfaya eklenip eklenmeyeceğini denetleyin.

Görüntüler / ekran görüntüleri

Ekran görüntülerini tedbirli kullanın. Belgelerde görüntülerin bakımı çok fazla iştir, küçük kullanıcı arabirimi değişiklikleri çok fazla ekran görüntüsü güncelliğini yitirebilir. Aşağıdaki kurallar bakım çalışmalarını azaltır:

  1. Metinde açıklanabilir şeyler için ekran görüntülerini kullanmayın. Özellikle özellik adlarını ve değerlerini göstermek amacıyla hiçbir zaman özellik kılavuzunun ekran görüntüsünü alma.
  2. Ekran görüntüsüne gösterilenle ilgisiz öğeleri eklemeyin. Örneğin, bir işleme efekti gösterildiğinde, görünüm penceresi ekran görüntüsünü alın, ancak çevresindeki tüm kullanıcı arabirimini dışlayın. Bazı kullanıcı arabirimini göstererek, pencereleri yalnızca önemli bölümün görüntüde yer alabilecek şekilde hareket ettirmeyi deneyin.
  3. Ekran görüntüsü kullanıcı arabirimini eklerken yalnızca önemli bölümleri gösterin. Örneğin, bir araç çubuğundaki düğmelerden bahsederken, önemli araç çubuğu düğmelerini gösteren küçük bir resim yapın, ancak çevresindeki her şeyi hariç tutun.
  4. Yalnızca yeniden oluşturması kolay görüntüleri kullanın. Bu, işaretçileri veya vurguları ekran görüntülerine boyamama anlamına gelir. İlk olarak, bunların nasıl görünmesi gerektiği konusunda tutarlı bir kural yoktur. İkincisi, böyle bir ekran görüntüsünü yeniden oluşturmak ek çaba gerektirir. Bunun yerine, metindeki önemli bölümleri açıklayın. Bu kuralın istisnaları vardır, ancak bunlar nadirdir.
  5. Açıkçası, animasyonlu bir GIF'i yeniden oluşturmak çok daha fazla çaba gerektirir. Zaman sonuna kadar yeniden oluşturmaktan veya insanların bu zamanı harcamak istememeleri durumunda çöpe atmasını beklemekten sorumlu olun.
  6. Makaledeki görüntü sayısını düşük tutun. Genellikle iyi bir yöntem, her şeyi gösteren ve gerisini metinde açıklayan bir aracın genel ekran görüntüsünü oluşturmaktır. Bu, gerektiğinde ekran görüntüsünü değiştirmeyi kolaylaştırır.

Diğer bazı yönler:

  • Ekran görüntüleri için düzenleyici kullanıcı arabirimi, tüm kullanıcıların koyu temaya erişimi olmadığından açık gri tema düzenleyicisini kullanmalıdır ve her şeyi mümkün olduğunca tutarlı tutmak istiyoruz.
  • Çoğu monitörde iyi göründüğü için varsayılan görüntü genişliği 500 pikseldir. Çok fazla sapmamaya çalış. En fazla 800 piksel genişlik olmalıdır.
  • Kullanıcı arabirimi ekran görüntüleri için PNG'leri kullanın.
  • 3B görünüm penceresi ekran görüntüleri için PNG'leri veya JPG'leri kullanın. Sıkıştırma oranı yerine kaliteyi tercih edin.

Bileşen özellikleri listesi

Özelliklerin listesini belgelerken, özellik adını vurgulamak için kalın metin kullanın, sonra bunları açıklamak için satır sonları ve normal metin kullanın. Alt bölümleri veya madde işareti listelerini kullanmayın.

Ayrıca, tüm cümleleri nokta ile bitirmeyi unutmayın.

Sayfa tamamlama denetim listesi

  1. Bu belgenin yönergelerine uyulduğundan emin olun.
  2. Belge yapısına göz atın ve diğer sayfaların Ayrıca bkz. bölümünde yeni belgeden bahsedilip bahsedilemediğine bakın.
  3. Varsa, konu hakkında bilgi sahibi olan birinin teknik doğruluk için sayfayı okumasını sağlayın.
  4. Stil ve biçimlendirme için birinin sayfayı okumasını sağlama. Bu konu başlığına aşina olmayan biri olabilir. Bu, belgelerin ne kadar anlaşılır olduğu hakkında geri bildirim almak için de iyi bir fikirdir.

Kaynak belgeleri

API belgeleri MRTK kaynak dosyalarından otomatik olarak oluşturulur. Bunu kolaylaştırmak için kaynak dosyaların aşağıdakileri içermesi gerekir:

Yukarıdakilere ek olarak, bakım, hata düzeltmeleri ve özelleştirme kolaylığı sağlamak için kod iyi yorumlanmalıdır.

Sınıf, yapı, sabit listesi özet blokları

MRTK'ye bir sınıf, yapı veya sabit listesi ekleniyorsa, amacı açıklanmalıdır. Bu, sınıfın üzerinde bir özet bloğunun biçimini almaktır.

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

Sınıf düzeyi bağımlılıkları varsa, bunlar özetin hemen altında bir açıklama bloğunda belgelenmelidir.

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

Sınıflar, yapılar veya sabit listeleri için özetler olmadan gönderilen Çekme İstekleri onaylanmaz.

Özellik, yöntem, olay özet blokları

Özellikler, yöntemler ve olaylar (PME) ve alanlar, kod görünürlüğünden (genel, özel, korumalı ve iç) bağımsız olarak özet bloklarla belgelenmelidir. Belge oluşturma aracı, yalnızca genel ve korumalı özellikleri filtrelemek ve yayımlamaktan sorumludur.

NOT: Unity yöntemleri için bir özet bloğu gerekli değildir (örneğin: Uyanık, Başlat, Güncelleştir).

Çekme isteğinin onaylanması için PME belgeleri gereklidir .

PME özet bloğunun bir parçası olarak, parametrelerin ve döndürülen verilerin anlamı ve amacı gereklidir.

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

Özellik giriş sürümü ve bağımlılıkları

API özet belgelerinin bir parçası olarak, özelliğin sunulduğu MRTK sürümüyle ilgili bilgiler ve bağımlılıklar bir açıklama bloğunda belgelenmelidir.

Bağımlılıklar uzantı ve/veya platform bağımlılıklarını içermelidir.

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

Serileştirilmiş alanlar

Denetçide betiğin alanları için çalışma zamanı belgeleri sağlamak üzere Unity'nin araç ipucu özniteliğini kullanmak iyi bir uygulamadır.

Yapılandırma seçeneklerinin API belgelerine eklenmesi için betiklerin en azından bir özet bloğuna araç ipucu içeriğini içermesi gerekir.

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

Numaralandırma değerleri

Tanımlama ve numaralandırma sırasında kod, özet bloğu kullanarak numaralandırma değerlerinin anlamını da belgelemelidir. Açıklama blokları, daha iyi anlaşılması için ek ayrıntılar sağlamak için isteğe bağlı olarak kullanılabilir.

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

Nasıl yapılır belgeleri

Karma Gerçeklik Toolkit'in birçok kullanıcısının API belgelerini kullanması gerekmeyebilir. Bu kullanıcılar deneyimlerini oluşturmak için önceden hazırlanmış, yeniden kullanılabilir ön deneyimlerimizden ve betiklerimizden yararlanacaktır.

Her özellik alanı, sağlananları oldukça yüksek düzeyde açıklayan bir veya daha fazla markdown (.md) dosyası içerir. Belirli bir özellik alanının boyutuna ve/veya karmaşıklığına bağlı olarak, sağlanan özellik başına bir dosyaya kadar ek dosyalar gerekebilir.

Bir özellik eklendiğinde (veya kullanım değiştirildiğinde), genel bakış belgeleri sağlanmalıdır.

Bu belgelerin bir parçası olarak, kullanmaya başlama konusunda yeni bir özellik veya kavram edinen müşterilere yardımcı olmak için çizimler de dahil olmak üzere nasıl yapılır bölümleri sağlanmalıdır.

Tasarım belgeleri

Karma Gerçeklik tamamen yeni dünyalar oluşturma fırsatı sunar. Bunun bir kısmı büyük olasılıkla MRTK ile kullanılmak üzere özel varlıkların oluşturulmasını içerir. Bunu müşteriler için mümkün olduğunca sorunsuz hale getirmek için bileşenler, tüm biçimlendirmeleri veya sanat varlıklarına yönelik diğer gereksinimleri açıklayan tasarım belgeleri sağlamalıdır.

Tasarım belgelerinin yararlı olabileceği bazı örnekler:

  • İmleç modelleri
  • Uzamsal eşleme görselleştirmeleri
  • Ses efekti dosyaları

Bu tür belgeler kesinlikle önerilir ve çekme isteği gözden geçirmesinin bir parçası olarak istenebilir.

Bu, MS Geliştirici sitesindeki tasarım önerisinden farklı olabilir veya olmayabilir

Performans notları

Bazı önemli özelliklerin performans maliyeti vardır. Bu kod genellikle nasıl yapılandırıldıklarına bağlı olarak çok fazla olacaktır.

Örneğin:

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

Cpu ve/veya GPU ağır bileşenleri için performans notları önerilir ve çekme isteği incelemesinin bir parçası olarak istenebilir . Geçerli performans notları API ve genel bakış belgelerine dahil edilir.

Hataya neden olan değişiklikler

Hataya neden olan değişiklikler belgeleri, her özellik alanının tek tek breaking-changes.md bağlanan bir üst düzey dosyadan oluşur.

Özellik alanı breaking-changes.md dosyaları, belirli bir sürüm için bilinen tüm hataya neden olan değişikliklerin listesini ve geçmiş sürümlerden gelen hataya neden olan değişikliklerin geçmişini içerir.

Örneğin:

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

Özellik düzeyi breaking-changes.md dosyalarında yer alan bilgiler, her yeni MRTK sürümünün sürüm notlarına toplanır.

Bir değişikliğin parçası olan tüm hataya neden olan değişiklikler Çekme İsteğinin parçası olarak belgelenmelidir.

MarkDown'i düzenleme araçları

Visual Studio Code , MRTK belgelerinin bir parçası olan markdown dosyalarını düzenlemek için harika bir araçtır.

Belge yazarken aşağıdaki iki uzantının yüklenmesi de kesinlikle önerilir:

  • Visual Studio Code için Docs Markdown Uzantısı - Belge yazma seçenekleri menüsünü getirmek için Alt+M tuşlarını kullanın.

  • Kod Yazım Denetleyicisi - yanlış yazılmış sözcüklerin altı çizili olacak; yanlış yazılmış bir sözcüğe sağ tıklayarak değiştirin veya sözlüğe kaydedin.

Bunların her ikisi de Microsoft tarafından yayımlanan Docs Yazma Paketi'nde paketlenmiştir.

Ayrıca bkz.