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, yaygın tuzakları vurgulamak ve önerilen yazma stilini açıklamak için giriş sağlar.

Sayfanın kendisi örnek olarak görev akla gelir, bu nedenle belgelerde amaçlanan stili 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şluk içeren iç içe yerleştirilmiş numaralandırılmış listeler
    2. Koddaki gerçek sayı ilgisizdir; ayrıştırma, doğru öğe numarasını ayarlamayı üstlenir.
  • Madde işareti noktası listeleri
    • İç içe madde işareti noktaları listeleri
  • **Çift yıldız** ile kalın metin
  • _underscore_ veya *tek yıldız* içeren italikmetin
  • 'Ters tırnak kullanarak' cümle içindeki metin highlighted as code
  • Docs 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ştirerek ve küçük harfe dönüştürerek oluşturulur

Kod örnekleri için üç ''' ters 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.

Todos

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

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

  1. Github'da TODO'ya ilişkin 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ığının hemen sonrasındaki bölüm, bölümün konusuna kısa bir giriş niteliğinde olmalıdır. Bunu fazla uzun kullanmayın, 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ü

Çoğu sayfa 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 metni içinde de görüntülenebilir, 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 eklenmemelidir. 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 giriş 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 tablosu dosyasına bağlanabilen bir içindekiler tablosu dosyası olabilir.

Stil

Yazma stili

Genel kural: Profesyonel olmaya çalışın. Bu genellikle "konuşma tonlarından" 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ı heyecanlanmaktan kaçının, hiçbir şey satmamıza gerek yok.
  7. Benzer şekilde, aşırı dramatik olmaktan kaçının. Ünlem işaretine nadiren ihtiyaç duyulmaktadır.

Büyük harf

  • Başlıklar için Tümce büyük/küçük harflerini kullanın. Yani. 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: bunları kalın veya italik yapmak. Kalın metnin etkisi, kalın metnin dışarıda kalmalarıdır ve bu nedenle bir metin parçası kaydırılırken ve hatta bir sayfa üzerinde kaydırılırken kolayca fark edilebilir. Kalın, kişilerin hatırlaması gereken ifadeleri 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 belirli bir terimi vurgulamak ister, çünkü özel bir anlamı vardır. Bu tür şeylerin genel metinden farklı olması gerekmez. Bir şeyi vurgulamak için basit bir yöntem olarak italik metin 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 edin.

Genel olarak, gereksiz metin vurgulamalarından kaçınmaya çalışın. Okuyucuyu haberdar etmek için özel terimler bir kez vurgulanabilir, metin boyunca bu tür vurgulamaları tekrar etmeyin, artık bir amaca hizmet etmediğinde ve yalnızca dikkat dağıtıcı olduğunda.

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 eklenir. Bir okuyucunun sayfadaki her bağlantıya tıklayacağını ve aynı sayfa 20 kez açılırsa ne kadar rahatsız edici olacağını düşüneceğini varsayalım.

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

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 listelenmeyeceğ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ını yapmak çok fazla iştir, küçük kullanıcı arabirimi değişiklikleri birçok ekran görüntüsünün 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 kullanıcı arabirimini dışlayın. Bazı kullanıcı arabirimini göstererek, pencereleri görüntüde yalnızca önemli bir parça olacak şekilde taşımayı 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üneceğine dair tutarlı bir kural yoktur. İkincisi, böyle bir ekran görüntüsünü yeniden oluşturmak ek çabadır. 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 harcanacak. Zaman sonuna kadar yeniden oluşturmaktan sorumlu olmak veya insanların bu zamanı harcamak istememeleri durumunda çöpe atmasını beklemek.
  6. Makaledeki görüntü sayısını düşük tutun. Genellikle iyi bir yöntem, her şeyi gösteren bir aracın genel ekran görüntüsünü oluşturmak ve gerisini metinde açıklamaktır. Bu, gerektiğinde ekran görüntüsünün değiştirilmesini 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 ve her şeyin mümkün olduğunca tutarlı olmasını istediğimizden açık gri tema düzenleyicisi kullanmalıdır.
  • Çoğu monitörde düzgün göründüğü için varsayılan görüntü genişliği 500 pikseldir. Bundan ç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 özelliklerinin listesi

Bir özellik listesini belgelerken, özellik adını vurgulamak için kalın metin kullanın, ardından 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ğuna 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ı prova okumasını sağlayın. 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'ya 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üzeyinde 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 özeti blokları

Özellikler, yöntemler ve olaylar (PME' ler) 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: Awake, Start, Update).

Ç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>

Özelliğe 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>

Seri hale getirilmiş 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 belgelerinde yer alabilmesi için betiklerin en azından araç ipucu içeriğini bir özet bloğuna eklemesi 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 sabit listesi 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 koşullarımızdan ve betiklerimizden yararlanacaktır.

Her özellik alanı, sağlanan özellikleri oldukça yüksek bir 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 en fazla bir tane olmak üzere ek dosyalar gerekebilir.

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

Bu belgenin bir parçası olarak, yeni bir özelliği veya kavramı kullanmaya başlayan 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 bölümü, MRTK ile kullanılmak üzere özel varlıkların oluşturulmasını da kapsayabilirsiniz. Bunu müşteriler için mümkün olduğunca sorunsuz hale getirmek için bileşenler, sanat varlıklarına yönelik tüm biçimlendirmeleri veya 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 değişir.

Örnek:

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.

Yeni 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 listesinin yanı sıra geçmiş sürümlerden gelen hataya neden olan değişikliklerin geçmişini içerir.

Örnek:

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 bir parçası olarak belgelenmelidir .

MarkDown 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ü açmak 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.