Wskazówki dotyczące dokumentacji

MRTK

W tym dokumencie opisano wytyczne i standardy dokumentacji dla zestawu narzędzi Mixed Reality Toolkit (MRTK). Zapewnia to wprowadzenie do technicznych aspektów dokumentacji pisania i generowania, aby wyróżnić typowe pułapki i opisać zalecany styl pisania.

Sama strona ma służyć jako przykład, dlatego używa zamierzonego stylu i najbardziej typowych 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 z co najmniej 3 wiodącymi pustymi spacjami
    2. Rzeczywista liczba w kodzie jest nieistotna; Analizowanie zajmie się ustawieniem poprawnego numeru elementu.
  • Listy punktorów
    • Zagnieżdżone listy punktorów
  • Tekst pogrubiony z **podwójną gwiazdką**
  • italictext z znakiem _underscore_ lub *pojedynczą gwiazdką*
  • Tekst highlighted as code w zdaniu "używanie backquotes"
  • Linki do stron dokumentów — wskazówki dotyczące dokumentacji zestawu narzędzi MRTK
  • Linki do kotwic na stronie; Kotwice są tworzone przez zastępowanie spacji kreskami i konwertowanie na małe litery

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

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

Podczas wzmianki o kodzie w zdaniu use a single backtick.

Todos

Unikaj używania obiektów TODO w dokumentach, ponieważ w miarę upływu czasu te obiekty TOD (takie jak obiekty TODO kodu) mają tendencję do gromadzenia się i informacji o tym, jak powinny być aktualizowane i dlaczego zostaną utracone.

Jeśli jest to absolutnie konieczne do dodania funkcji TODO, wykonaj następujące kroki:

  1. Zgłoś nowy problem w witrynie GitHub opisujący kontekst zadania TODO i podaj wystarczające tło, aby inny współautor mógł zrozumieć, a następnie rozwiązać ten problem.
  2. Odwołaj się do adresu URL problemu w zadaniach do wykonania w dokumentacji.

<!-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: Krótki rozmycie problemu ->

Wyróżnione sekcje

Aby wyróżnić określone punkty dla czytelnika, 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 głównym tytule rozdziału powinna służyć jako krótkie wprowadzenie do tego, o czym jest rozdział. Nie należy tego robić zbyt długo, zamiast tego dodaj nagłówki podrzędne. Umożliwiają one łączenie z sekcjami i można je zapisać jako zakładki.

Treść główna

Użyj nagłówków dwupoziomowych i trzypoziomowych, aby określić strukturę 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 nagłówkami czterech poziomó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 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 (TOC)

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. W folderze dokumentacji może istnieć plik toc dla każdego podfolderu, 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 unikanie "tonu konwersacyjnego". Spróbuj również uniknąć hiperboli i sensacji.

  1. Nie próbuj być (nadmiernie) zabawny.
  2. Nigdy nie pisze "I"
  3. Unikaj "my". Zwykle można to łatwo przereślić, zamiast tego za pomocą "MRTK". Przykład: "Obsługujemy tę funkcję" —> "MRTK obsługuje tę funkcję" lub "obsługiwane są następujące funkcje...".
  4. Podobnie spróbuj uniknąć "ty". Przykład: "Dzięki tej prostej zmianie cieniator staje się konfigurowalny!" —> "Cieniowania można skonfigurować przy niewielkim wysiłku".
  5. Nie używaj "niechlujnych fraz".
  6. Unikaj brzmiąc zbyt podekscytowany, nie musimy sprzedawać niczego.
  7. Podobnie unikaj nadmiernego dramatycznego bycia. Wykrzyknik rzadko jest potrzebny.

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 wszystkich innych elementów. 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 słów, zobacz poniżej.
  • Gdy link jest osadzony w zdaniu (która jest preferowaną metodą), standardowa nazwa rozdziału zawsze używa wielkie litery, co powoduje niezgodność reguły bez wprowadzania wielkich liter wewnątrz tekstu. W związku z tym użyj niestandardowej nazwy linku, aby naprawić literę. Na przykład poniżej znajduje się link do dokumentacji dotyczącej kontroli granic .
  • Do capitalize nazw, takich jak Unity.
  • Nie należy 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 sprawiają, że są kursywą. Efektem pogrubionego tekstu jest to, że pogrubiony tekst wystanie 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 jeden z nich chce albo "grupować" coś, co należy logicznie do siebie lub wyróżnić określony termin, ponieważ ma specjalne znaczenie. Takie rzeczy nie muszą wyróżniać się ogólnym tekstem. Użyj tekstu kursywowego 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, spróbuj uniknąć niepotrzebnego wyróżniania tekstu. Specjalne terminy można wyróżnić raz, aby czytelnik wiedział, nie powtarzać takiego wyróżniania w całym tekście, gdy nie służy już do celów i tylko rozprasza.

Wymienianie wpisów 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 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, aby 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 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 zestawu narzędzi Mixed Reality Może nie być konieczne użycie 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 o dużym obciążeniu 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ść składa się z pliku najwyższego poziomu, który łączy się z poszczególnymi breaking-changes.md poszczególnych obszarów funkcji.

Obszar funkcji breaking-changes.md plików 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 instalowanie następujących dwóch rozszerzeń jest również zdecydowanie zalecane:

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

  • Sprawdzanie pisowni kodu — 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ż