Wskazówki dotyczące dokumentacji — MRTK2

  • Artykuł
ZESTAW NARZĘDZI MRTK

W tym dokumencie opisano wytyczne i standardy dokumentacji dotyczące zestawu narzędzi Mixed Reality Toolkit (MRTK). Stanowi to wprowadzenie do technicznych aspektów pisania i generowania dokumentacji, wyróżniania typowych pułapek oraz opisywania zalecanego stylu pisania.

Sama strona ma służyć jako przykład, dlatego używa zamierzonego stylu i najpopularniejszych funkcji znaczników dokumentacji.

Funkcje i adiustacja

W tej sekcji opisano często potrzebne funkcje. Aby zobaczyć, jak działają, przyjrzyj się kodowi źródłowemu strony.

  1. Numerowane
    1. Zagnieżdżone listy numerowane z co najmniej 3 wiodącymi pustymi spacjami
    2. Rzeczywista liczba w kodzie jest nieistotna; Analizowanie zajmie się ustawieniem poprawnego numeru elementu.

W przypadku przykładów kodu używamy bloków z trzema backticksami "" i określamy csharp jako język wyróżniania składni:

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

W przypadku wzmianki o kodzie w zdaniu use a single backtick.

Todos

Unikaj używania obiektów TODO w dokumentach, ponieważ wraz z upływem czasu te obiekty TOD (takie jak kod TODO) mają tendencję do gromadzenia się i informacji o sposobie ich aktualizowania i przyczynach utraty.

Jeśli jest to absolutnie konieczne, aby dodać todo, wykonaj następujące kroki:

  1. Utwórz nowy problem w usłudze GitHub opisujący kontekst zadania TODO i podaj wystarczające doświadczenie, aby inny współautor mógł zrozumieć, a następnie rozwiązać ten problem.
  2. Odwoływanie się do adresu URL problemu w todo w dokumentacji.

<-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Krótki blurb na ten problem ->

Wyróżnione sekcje

Aby wyróżnić określone punkty dla czytnika, użyj polecenia > [! UWAGA] , > [! OSTRZEŻENIE] i > [! WAŻNE] aby utworzyć następujące style. Zaleca się używanie notatek dla ogólnych punktów i punktów ostrzegawczych/ważnych tylko w przypadku istotnych przypadków.

Uwaga

Przykład notatki

Ostrzeżenie

Przykład ostrzeżenia

Ważne

Przykład ważnego komentarza

Układ strony

Wprowadzenie

Część bezpośrednio po tytule rozdziału głównego powinna służyć jako krótkie wprowadzenie do tego, o czym chodzi. Nie należy tego robić zbyt długo, zamiast tego dodawać nagłówki podrzędne. Umożliwiają one łączenie się z sekcjami i można je zapisać jako zakładki.

Część główna

Użyj dwupoziomowych i trzech poziomów nagłówków, aby sstrukturę reszty.

Mini sekcje

Użyj pogrubionego wiersza tekstu dla bloków, które powinny wyróżniać się. W pewnym momencie możemy zastąpić to czterema poziomami nagłówków.

Sekcja "Zobacz również"

Większość stron powinna kończyć się rozdziałem o nazwie Zobacz również. Ten rozdział to po prostu punktowana lista linków do stron związanych z tym tematem. Te linki mogą również pojawiać się w tekście strony, jeśli jest to konieczne, ale nie jest to wymagane. Podobnie tekst strony może zawierać linki do stron, które nie są powiązane z tematem głównym. Nie powinny one być uwzględniane na liście Zobacz również . Zobacz rozdział "Zobacz również" tej strony jako przykład wyboru linków.

Spis treści (SPIS TREŚCI)

Pliki toc są używane do generowania pasków nawigacji w dokumentacji github.io zestawu narzędzi MRTK. Za każdym razem, gdy zostanie dodany nowy plik dokumentacji, upewnij się, że istnieje wpis dla tego pliku w jednym z plików toc.yml folderu dokumentacji. Tylko artykuły wymienione w plikach toc będą wyświetlane w nawigacji dokumentów deweloperów. Dla każdego podfolderu w folderze dokumentacji może istnieć plik toc, który można połączyć z dowolnym istniejącym plikiem toc, aby dodać go jako podsekcję do odpowiedniej części nawigacji.

Styl

Styl pisania

Ogólna zasada kciuka: Spróbuj brzmieć profesjonalnie. Zwykle oznacza to uniknięcie "tonu konwersacyjnego". Spróbuj również uniknąć hiperboli i sensacji.

  1. Nie staraj się być (overly) zabawne.
  2. Nigdy nie piszę "I"
  3. Unikaj "my". Zwykle można to łatwo przereślić przy użyciu zestawu narzędzi MRTK. Przykład: "obsługujemy tę funkcję" —> "zestaw narzędzi MRTK obsługuje tę funkcję" lub "obsługiwane są następujące funkcje...".
  4. Podobnie staraj się unikać "ty". Przykład: "Dzięki tej prostej zmianie cieniator staje się konfigurowalny!" —> "Cieniowania można skonfigurować przy niewielkim nakładzie pracy".
  5. Nie używaj "niechlujnych fraz".
  6. Unikaj brzmiąc zbyt podekscytowany, nie musimy nic sprzedawać.
  7. Podobnie unikaj nadmiernego dramatycznego bycia. Wykrzykniki są rzadko potrzebne.

Wielkości liter

  • Użyj wielkości liter zdania dla nagłówków. Ie. wielką literą i nazwiskami, ale nic innego.
  • Używaj zwykłego języka angielskiego dla wszystkiego innego. Oznacza to, że nie wielką literą dowolnych słów, nawet jeśli posiadają specjalne znaczenie w tym kontekście. Preferuj tekst kursywy do wyróżniania niektórych wyrazów, zobacz poniżej.
  • Gdy link jest osadzony w zdaniu (co jest preferowaną metodą), standardowa nazwa rozdziału zawsze używa wielkie litery, co powoduje niezgodność reguły bez wielkich liter wewnątrz tekstu. W związku z tym użyj niestandardowej nazwy łącza, aby naprawić wielkość liter. Na przykład poniżej znajduje się link do dokumentacji dotyczącej kontrolek granic .
  • Do wielkich nazw, takich jak Unity.
  • Nie wielką literą "edytora" podczas pisania edytora aparatu Unity.

Wyróżnienie i wyróżnienie

Istnieją dwa sposoby wyróżniania lub wyróżniania słów, dzięki czemu są pogrubione lub kursywa. Efektem pogrubionego tekstu jest to, że tekst pogrubiony wystaje i dlatego można łatwo zauważyć podczas odtłuszczania fragmentu tekstu, a nawet po prostu przewijania strony. Pogrubienie doskonale wyróżnia frazy, które należy zapamiętać. Jednak rzadko używaj pogrubionego tekstu, ponieważ zwykle rozprasza się.

Często użytkownik chce "grupować" coś, co należy logicznie do siebie, lub wyróżnić konkretny termin, ponieważ ma specjalne znaczenie. Takie rzeczy nie muszą wyróżniać się ogólnym tekstem. Użyj tekstu kursywy jako lekkiej metody , aby wyróżnić coś.

Podobnie, gdy nazwa pliku, ścieżka lub wpis menu jest wymieniony w tekście, preferuj kursywę, aby logicznie ją zgrupować, bez rozpraszania uwagi.

Ogólnie rzecz biorąc, staraj się unikać niepotrzebnego wyróżniania tekstu. Specjalne terminy można wyróżnić raz, aby czytelnik był świadomy, nie powtarzać takiego wyróżniania w całym tekście, gdy nie służy już do celów i rozpraszać uwagę.

Wspominanie o wpisach menu

Podczas wzmianki o wpisie menu, który użytkownik powinien kliknąć, bieżąca konwencja to: Project > Files > Create > Leaf

Wstaw jak najwięcej przydatnych linków do innych stron, ale każde łącze tylko raz. Załóżmy, że czytelnik kliknie każdy link na stronie i pomyśl o tym, jak irytujące byłoby to, jeśli ta sama strona zostanie otwarta 20 razy.

Preferuj łącza osadzone w zdaniu:

  • ŹLE: Wskazówki są przydatne. Aby uzyskać szczegółowe informacje, zobacz ten rozdział .
  • DOBRE: Wskazówki są przydatne.

Unikaj linków zewnętrznych, mogą stać się nieaktualne lub zawierać zawartość praw autorskich.

Podczas dodawania linku należy również rozważyć, czy powinien on być również wymieniony w sekcji Zobacz również . Podobnie sprawdź, czy do strony połączonej należy dodać link do nowej strony.

Obrazy/zrzuty ekranu

Używaj zrzutów ekranu oszczędnie. Obsługa obrazów w dokumentacji jest duża, małe zmiany interfejsu użytkownika mogą powodować nieaktualne zrzuty ekranu. Następujące reguły zmniejszają nakład pracy konserwacyjnej:

  1. Nie używaj zrzutów ekranu dla elementów, które można opisać w tekście. Zwłaszcza nigdy nie zrzut ekranu siatki właściwości w celu wyświetlania nazw i wartości właściwości.
  2. Nie należy uwzględniać elementów na zrzucie ekranu, które są nieistotne dla wyświetlanych elementów. Na przykład po wyświetleniu efektu renderowania utwórz zrzut ekranu przedstawiający port widoku, ale wyklucz dowolny interfejs użytkownika. Pokazano interfejs użytkownika, spróbuj przenieść okna wokół tak, że tylko ta ważna część znajduje się na obrazie.
  3. W przypadku dołączania interfejsu użytkownika zrzutu ekranu pokaż tylko ważne części. Na przykład podczas mówienia o przyciskach na pasku narzędzi utwórz mały obraz przedstawiający ważne przyciski paska narzędzi, ale wyklucz wszystko wokół niego.
  4. Używaj tylko obrazów, które są łatwe do odtworzenia. Oznacza to, że nie maluj znaczniki ani wyróżniaj na zrzutach ekranu. Po pierwsze, nie ma spójnych reguł, jak te powinny wyglądać, mimo to. Po drugie odtwarzanie takiego zrzutu ekranu jest dodatkowym nakładem pracy. Zamiast tego opisz ważne części tekstu. Istnieją wyjątki od tej reguły, ale są rzadkie.
  5. Oczywiście jest to o wiele więcej wysiłku, aby odtworzyć animowany gif. Spodziewaj się, że będzie odpowiedzialny za odtworzenie go do końca czasu lub spodziewaj się, że ludzie go wyrzucą, jeśli nie chcą spędzać tego czasu.
  6. Zachowaj niską liczbę obrazów w artykule. Często dobrą metodą jest utworzenie jednego ogólnego zrzutu ekranu narzędzia, które pokazuje wszystko, a następnie opisz resztę w tekście. Dzięki temu można łatwo zastąpić zrzut ekranu w razie potrzeby.

Inne aspekty:

  • Interfejs użytkownika edytora dla zrzutów ekranu powinien używać jasnoszary edytor motywu, ponieważ nie wszyscy użytkownicy mają dostęp do ciemnego motywu i chcemy zachować spójność elementów tak spójnych, jak to możliwe.
  • Domyślna szerokość obrazu to 500 pikseli, ponieważ jest ona wyświetlana również na większości monitorów. Spróbuj nie odejść zbyt wiele od niego. Szerokość 800 pikseli powinna być maksymalna.
  • Użyj grup pngs na zrzutach ekranu interfejsu użytkownika.
  • Użyj grup PNG lub jpG na potrzeby zrzutów ekranu widoku 3D. Preferuj jakość w stosunku do kompresji.

Lista właściwości składników

Podczas dokumentowania listy właściwości użyj pogrubionego tekstu, aby wyróżnić nazwę właściwości, a następnie podziały wierszy i zwykły tekst, aby je opisać. Nie należy używać pod rozdziałów ani list punktów punktowych.

Nie zapomnij również zakończyć wszystkich zdań kropką.

Lista kontrolna uzupełniania strony

  1. Upewnij się, że zostały spełnione wytyczne tego dokumentu.
  2. Przejrzyj strukturę dokumentu i sprawdź, czy nowy dokument można wymienić w sekcji Zobacz również inne strony.
  3. Jeśli jest dostępna, poproś kogoś o zapoznanie się z weryfikacją tematu w celu odczytania strony pod kątem poprawności technicznej.
  4. Poproś kogoś o przeczytanie strony pod kątem stylu i formatowania. Może to być ktoś nieznany z tematem, który jest również dobrym pomysłem, aby uzyskać opinię na temat tego, jak zrozumiała jest dokumentacja.

Dokumentacja źródłowa

Dokumentacja interfejsu API zostanie wygenerowana automatycznie z plików źródłowych zestawu narzędzi MRTK. Aby to ułatwić, pliki źródłowe muszą zawierać następujące elementy:

Oprócz powyższych kod powinien być dobrze skomentowany, aby umożliwić konserwację, poprawki błędów i łatwość dostosowywania.

Bloki podsumowania klasy, struktury i wyliczenia

Jeśli do zestawu NARZĘDZI MRTK jest dodawana klasa, struktura lub wyliczenie, należy opisać jego przeznaczenie. Ma to na celu utworzenie bloku podsumowania nad klasą.

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

Jeśli istnieją jakiekolwiek zależności na poziomie klasy, powinny one być udokumentowane w bloku uwag, bezpośrednio poniżej podsumowania.

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

Żądania ściągnięcia przesłane bez podsumowań dla klas, struktur lub wyliczenia nie zostaną zatwierdzone.

Właściwość, metoda, bloki podsumowania zdarzeń

Właściwości, metody i zdarzenia (PME) oraz pola mają być udokumentowane blokami podsumowania, niezależnie od widoczności kodu (publicznej, prywatnej, chronionej i wewnętrznej). Narzędzie generowania dokumentacji jest odpowiedzialne za filtrowanie i publikowanie tylko funkcji publicznych i chronionych.

UWAGA: Blok podsumowania nie jest wymagany dla metod aparatu Unity (np. Awake, Start, Update).

Do zatwierdzenia żądania ściągnięcia wymagana jest dokumentacja narzędzia PME.

W ramach bloku podsumowania PME wymagane jest znaczenie i przeznaczenie parametrów i zwracanych danych.

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

Wersja i zależności wprowadzenia funkcji

W ramach dokumentacji podsumowania interfejsu API informacje dotyczące wersji zestawu narzędzi MRTK, w której wprowadzono tę funkcję, a wszelkie zależności powinny być udokumentowane w bloku uwag.

Zależności powinny obejmować zależności rozszerzenia i/lub platformy.

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

Pola serializowane

Dobrym rozwiązaniem jest użycie atrybutu etykietki narzędzia aparatu Unity w celu udostępnienia dokumentacji środowiska uruchomieniowego dla pól skryptu w inspektorze.

Aby opcje konfiguracji były uwzględnione w dokumentacji interfejsu API, skrypty muszą zawierać co najmniej zawartość etykietki narzędzia w bloku podsumowania.

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

Wartości wyliczenia

Podczas definiowania i wyliczania kod musi również udokumentować znaczenie wartości wyliczenia przy użyciu bloku podsumowania. Bloki uwagi mogą być opcjonalnie używane do udostępniania dodatkowych szczegółów w celu zwiększenia zrozumienia.

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

Dokumentacja instrukcji

Wielu użytkowników Mixed Reality Toolkit może nie potrzebować dokumentacji interfejsu API. Ci użytkownicy skorzystają z naszych wstępnie utworzonych prefab i skryptów wielokrotnego użytku, aby utworzyć swoje środowiska.

Każdy obszar funkcji będzie zawierać co najmniej jeden plik markdown (md), który opisuje na dość wysokim poziomie, co jest udostępniane. W zależności od rozmiaru i/lub złożoności danego obszaru funkcji może być konieczne dodatkowe pliki, maksymalnie jeden na jedną z dostępnych funkcji.

Po dodaniu funkcji (lub zmianie użycia) należy podać dokumentację przeglądową.

W ramach tej dokumentacji należy udostępnić sekcje z instrukcjami, w tym ilustracje, aby pomóc klientom w rozpoczęciu pracy z funkcją lub koncepcją.

Dokumentacja dotycząca projektowania

Mixed Reality daje możliwość tworzenia całkowicie nowych światów. Część tej funkcji może obejmować tworzenie niestandardowych zasobów do użycia z zestawem narzędzi MRTK. Aby zapewnić takie tarcie jak to możliwe dla klientów, składniki powinny dostarczać dokumentację projektową opisującą wszelkie wymagania dotyczące formatowania lub innych wymagań dotyczących zasobów artystycznych.

Niektóre przykłady, w których dokumentacja projektu może być przydatna:

  • Modele kursorów
  • Wizualizacje mapowania przestrzennego
  • Pliki efektów dźwiękowych

Ten typ dokumentacji jest zdecydowanie zalecany i może być żądany w ramach przeglądu żądania ściągnięcia.

Może się to różnić od zalecenia projektowego w witrynie dewelopera MS

Uwagi dotyczące wydajności

Niektóre ważne funkcje są kosztem wydajności. Często ten kod bardzo zależy od tego, jak są skonfigurowane.

Na przykład:

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.

Uwagi dotyczące wydajności są zalecane w przypadku składników intensywnie korzystających z procesora CPU i/lub procesora GPU i mogą być wymagane w ramach przeglądu żądania ściągnięcia. Wszelkie odpowiednie uwagi dotyczące wydajności należy uwzględnić w dokumentacji interfejsu API i przeglądu.

Fundamentalne zmiany

Dokumentacja zmian powodujących niezgodność polega na pliku najwyższego poziomu, który łączy się z poszczególnymi breaking-changes.md poszczególnych obszarów funkcji.

Obszar funkcji breaking-changes.md pliki mają zawierać listę wszystkich znanych zmian powodujących niezgodność dla danej wersji , a także historię zmian powodujących niezgodność z poprzednich wersji.

Na przykład:

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

Informacje zawarte na poziomie funkcji breaking-changes.md plików zostaną zagregowane do informacji o wersji dla każdej nowej wersji zestawu narzędzi MRTK.

Wszelkie zmiany powodujące niezgodność, które są częścią zmiany , muszą być udokumentowane w ramach żądania ściągnięcia.

Narzędzia do edycji języka MarkDown

Visual Studio Code to doskonałe narzędzie do edytowania plików markdown, które są częścią dokumentacji zestawu narzędzi MRTK.

Podczas pisania dokumentacji zdecydowanie zaleca się zainstalowanie następujących dwóch rozszerzeń:

  • Rozszerzenie języka Markdown witryny Docs dla Visual Studio Code — użyj klawiszy Alt+M, aby wyświetlić menu opcji tworzenia dokumentów.

  • Code Spell Checker — błędnie napisane wyrazy zostaną podkreślone; Kliknij prawym przyciskiem myszy błędnie napisany wyraz, aby go zmienić lub zapisać w słowniku.

Oba te pakiety są pakowane w opublikowanym przez firmę Microsoft pakiecie Docs Authoring Pack.

Zobacz też