Wskazówki dotyczące dokumentacji

MRTK

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

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


Funkcje i na znacznikach

W tej sekcji opisano często potrzebne funkcje. Aby zobaczyć, jak działają, zapoznaj się z kodem źródłowym strony.

  1. Numerowane
    1. Zagnieżdżone listy numerowane z co najmniej 3 wiodącymi pustymi spacjami
    2. Rzeczywista liczba w kodzie nie ma znaczenia. Analizowanie zajmie się ustawieniem poprawnego numeru elementu.
  • Listy punktorów
    • Zagnieżdżone listy punktorów
  • Tekst pogrubiony za pomocą * * podwójnej gwiazdki**
  • tekst kursywą z _ podkreśleniem lub _ pojedynczą * gwiazdką*
  • Tekst highlighted as code w zdaniu ` przy użyciu backquotes`
  • Linki do dokumentacji mrTK stron dokumentacji
  • Linki do kotwic na stronie; kotwice są formowane przez zamianę spacji na kreski i konwersję na małe litery

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

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

Podczas wspomniania kodu w zdaniu use a single backtick .

Todos

Unikaj używania toDO w cs, ponieważ z czasem te toDO (takie jak toDO kodu) zwykle kumulują się i zawierają informacje o tym, jak powinny być aktualizowane i dlaczego są utracone.

Jeśli dodanie toDO jest absolutnie konieczne, wykonaj następujące kroki:

  1. W serwisie Github w witrynie GitHub z opisem kontekstu tego zadania podaj wystarczającą ilość informacji, aby inny współautor mógł go zrozumieć, a następnie rozwiązać ten problem.
  2. Odwołaj się do adresu URL problemu w todo w dokumentów.

<!-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: A brief blurb on the issue -->

Wyróżnione sekcje

Aby wyróżnić określone punkty dla czytnika, użyj znaków > [!NOTE] , i , aby utworzyć następujące > [!WARNING] > [!IMPORTANT] style. Zaleca się używanie uwag dla punktów ogólnych i ostrzeżeń/ważnych punktów tylko w szczególnych istotnych przypadkach.

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 rozdziału. Nie należy czekać zbyt długo. Zamiast tego dodaj podsieć nagłówków. Umożliwiają one łączenie się z sekcjami i mogą być zapisywane jako zakładki.

Treść główna

Użyj nagłówków dwupoziomowych i trzypoziomowych, aby ujednać strukturę pozostałych.

Mini sekcje

Użyj pogrubionym wierszem tekstu dla bloków, które powinny się wyróżniać. W pewnym momencie możemy zastąpić to nagłówkami czteropoziomowym.

Sekcja "Zobacz też"

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 odpowiednim tekście strony, 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 należy ich uwzględniać na liście Zobacz również. Zobacz rozdział "Zobacz również" na tej stronie jako przykład dla wyboru linków.

Spis treści

Pliki toc są używane do generowania pasków nawigacji w dokumentacji github.io MRTK. Przy każdym dodaniu nowego pliku dokumentacji upewnij się, że w jednym z plików toc.yml folderu dokumentacji znajduje się wpis dla tego pliku. Tylko artykuły wymienione w plikach toc będą wyświetlane w nawigacji w dokumentów dla deweloperów. W folderze dokumentacji może być 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 reguła: Spróbuj brzmieć profesjonalnie. Zwykle oznacza to unikanie "tonu konwersacyjne". Staraj się również unikać hiperbolii i odczuć.

  1. Nie próbuj być (zbyt wiele).
  2. Nigdy nie pisz "I"
  3. Unikaj "my". Zazwyczaj można to łatwo zmienić, używając zamiast tego "MRTK". Przykład: "obsługujemy tę funkcję" — > "Zestaw 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 moduł cieniowania staje się konfigurowalny!" -> "Cieniowania można skonfigurować przy niewielkim na wysiłku".
  5. Nie używaj fraz "niechlujne frazy".
  6. Unikaj zbytniego ekscytowania się, nie musimy nic sprzedawać.
  7. Podobnie należy unikać zbyt radykalnych sytuacji. Wykrzyknik jest rzadko potrzebny.

Wielkości liter

  • Użyj przypadku zdań dla nagłówków. Ie. Pierwszą literę i nazwy należy ująć w pierwszą literę, ale nic innego.
  • We wszystkich innych językach używaj zwykłego języka angielskiego. Oznacza to, że nie należy oznaczać dowolnych słów literami, nawet jeśli mają specjalne znaczenie w tym kontekście. Preferuj kursywę tekstu 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 liter, co przerywa regułę nieużywaną liter w tekście. 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 sterowania granicami.
  • Nazwy, takie jak Unity, należy ująć w literę .
  • Nie należy oznaczać literą "editor" podczas pisania w edytorze aparatu Unity.

Wyróżnianie i wyróżnianie

Istnieją dwa sposoby wyróżniania lub wyróżniania wyrazów, dzięki czemu są pogrubione lub kursywą. Efektem pogrubienia tekstu jest to, że pogrubiony tekst jest wyklejony i w związku z tym można go łatwo zauważyć podczas szmugowania fragmentu tekstu, a nawet po prostu przewijania strony. Pogrubienie to doskonałe miejsce do wyróżniania fraz, które ludzie powinni zapamiętać. Jednak rzadko używaj pogrubienia tekstu, ponieważ zwykle rozprasza on uwagę.

Często trzeba "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 kursywą tekstu jako lekkiej metody wyróżniania.

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

Ogólnie rzecz biorąc, staraj się unikać niepotrzebnego wyróżniania tekstu. Terminy specjalne można wyróżnić raz, aby zwrócić uwagę czytelnika, nie powtarzaj takich wyróżnień w tekście, gdy nie służy już do żadnego celu i rozprasza uwagę.

Wzmianki o wpisach menu

W przypadku wspomniano 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żdy link tylko raz. Załóżmy, że czytelnik klika każdy link na stronie i zastanów się, jak może to być irytujące, jeśli ta sama strona zostanie otwarta 20 razy.

Preferuj linki osadzone w zdaniu:

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

Podczas dodawania linku zastanów się, czy powinien on być również wymieniony w sekcji Zobacz też. Podobnie sprawdź, czy link do nowej strony powinien zostać dodany do strony połączonej.

Obrazy/zrzuty ekranu

Używaj zrzutów ekranu oszczędnie. Obsługa obrazów w dokumentacji to dużo pracy. Niewielkie zmiany w interfejsie użytkownika mogą sprawić, że wiele zrzutów ekranu będzie nieaktualnych. Następujące reguły zmniejszają nakład pracy konserwacji:

  1. Nie używaj zrzutów ekranu dla rzeczy, które można opisać w tekście. W szczególności nigdy nie wyświetlaj zrzutu ekranu siatki właściwości wyłącznie w celu wyświetlania nazw właściwości i wartości.
  2. Nie uwzględniaj na zrzucie ekranu rzeczy, które nie mają znaczenia dla tego, co jest wyświetlane. Jeśli na przykład zostanie pokazany efekt renderowania, zrób zrzut ekranu przedstawiający ekran, ale z wykluczeniem dowolnego interfejsu użytkownika wokół niego. Wyświetlając jakiś interfejs użytkownika, spróbuj przenieść okna w taki sposób, aby na obrazie znajduje się tylko ta ważna część.
  3. W przypadku do uwzględnienia interfejsu użytkownika zrzutu ekranu pokaż tylko ważne części. Na przykład podczas rozmowy o przyciskach na pasku narzędzi zrób mały obraz, który pokazuje ważne przyciski paska narzędzi, ale wyklucz wszystkie wokół niego.
  4. Używaj tylko obrazów, które można łatwo odtworzyć. Oznacza to, że nie maluj znaczników ani wyróżnień na zrzutach ekranu. Po pierwsze, mimo to nie ma żadnych spójnych reguł, jak powinny one wyglądać. Po drugie odtworzenie takiego zrzutu ekranu jest dodatkowym wysiłkiem. Zamiast tego opisz ważne części tekstu. Istnieją wyjątki od tej reguły, ale są rzadkie.
  5. Oczywiście o wiele więcej wysiłku trzeba zrobić, aby odtworzyć animowany obraz GIF. Należy oczekiwać, że będzie on odpowiedzialny za odtworzenie go do końca czasu, lub oczekiwać, że ludzie go zrzucą, jeśli nie chcą poświęcać tego czasu.
  6. Zachowaj niską liczbę obrazów w artykule. Często dobrą metodą jest zrobić jeden ogólny zrzut ekranu przedstawiający wszystkie narzędzia, a następnie opisać pozostałe w tekście. Ułatwia to zastąpienie zrzutu ekranu w razie potrzeby.

Niektóre inne aspekty:

  • Interfejs użytkownika edytora zrzutów ekranu powinien używać jasnoszarego edytora motywów, ponieważ nie wszyscy użytkownicy mają dostęp do ciemnego motywu i chcemy zachować spójność.
  • Domyślna szerokość obrazu to 500 pikseli, ponieważ jest ona dobrze wyświetlana na większości monitorów. Staraj się nie odbiegać zbyt wiele od niego. Maksymalna szerokość to 800 pikseli.
  • Użyj PNG do zrzutów ekranu interfejsu użytkownika.
  • Użyj plików PNG lub JPEG w przypadku zrzutów ekranu w widoku 3D. Preferuj jakość zamiast współczynnika kompresji.

Lista właściwości składnika

Podczas dokumentowania listy właściwości użyj pogrubienia 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ć rozdziałów ani list punktorów.

Ponadto nie zapomnij zakończyć wszystkich zdań przy użyciu okresu.

Lista kontrolna uzupełniania stron

  1. Upewnij się, że zostały przestrzegane wytyczne tego dokumentu.
  2. Przejrzyj strukturę dokumentu i sprawdź, czy można wspomnieć o nowym dokumencie w sekcji Zobacz również na innych stronach.
  3. Jeśli jest dostępna, poślij osobę znaną na temat weryfikacji, aby przeczytać stronę w celu poprawienia poprawności technicznej.
  4. Poślij komuś weryfikację, aby przeczytać stronę pod tematem stylu i formatowania. Może to być osoba nieznajoma w tym temacie, co jest również dobrym pomysłem do uzyskania opinii o tym, jak zrozumiała jest dokumentacja.

Dokumentacja źródłowa

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

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

Bloki podsumowania klasy, struktury, wyliczenia

Jeśli klasa, struktura lub wyliczanie są dodawane do mrTK, jego przeznaczenie musi być opisane. Ma to postać bloku podsumowania powyżej klasy .

/// <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 uwagi, 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ęć przesłane bez podsumowań dla klas, struktur lub wyliczeń nie zostaną zatwierdzone.

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

Właściwości, metody i zdarzenia (PME), a także pola, mają być udokumentowane za pomocą bloków podsumowania, niezależnie od widoczności kodu (publiczne, prywatne, chronione i wewnętrzne). Narzędzie do 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ągnnięcia jest wymagana dokumentacja programu 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 do funkcji

W ramach dokumentacji podsumowania interfejsu API informacje dotyczące wersji zestawu danych MRTK, w której wprowadzono tę funkcję, oraz 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 zapewnienia dokumentacji środowiska uruchomieniowego dla pól skryptu w inspektorze.

Aby opcje konfiguracji były zawarte 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ż dokumentować znaczenie wartości wyliczeniowych przy użyciu bloku podsumowania. Bloki uwag mogą opcjonalnie służyć do zapewnienia dodatkowych szczegółów w celu lepszego 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 z how-to

Wielu użytkowników zestawu narzędzi Mixed Reality Toolkit może nie potrzebować korzystać z dokumentacji interfejsu API. Ci użytkownicy będą korzystać z naszych wstępnie niestandardowych prefabryktów i skryptów wielokrotnego użytku, aby tworzyć swoje środowisko.

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

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

W ramach tej dokumentacji należy dostarczać sekcje z daniem, w tym ilustracje, aby pomóc klientom w nowych funkcjach lub koncepcjach rozpoczynania pracy.

Dokumentacja dotycząca projektowania

Mixed Reality umożliwia tworzenie zupełnie nowych świata. Część tego może obejmować tworzenie zasobów niestandardowych do użycia z zestawem mrTK. Aby było to możliwie bezproblemowe dla klientów, składniki powinny dostarczać dokumentację projektową opisową wszelkich formatowania lub innych wymagań dotyczących zasobów artych.

Przykłady, w których dokumentacja projektowa może być pomocna:

  • Modele kursorów
  • Wizualizacje map przestrzennych
  • Pliki efektów dźwiękowych

Ten typ dokumentacji jest zdecydowanie zalecany i można go zażądać w ramach przeglądu żądania ściągnnięcia.

Może się to różnić od zalecenia dotyczącego projektu w witrynie MS Developer

Uwagi dotyczące wydajności

Niektóre ważne funkcje są dostępne kosztem wydajności. Często ten kod będzie bardzo zależny od konfiguracji.

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 z dużym obciążeniem procesora CPU i/lub procesora GPU i mogą być żądane w ramach przeglądu żądania ściągnnięcia. Wszelkie odpowiednie uwagi dotyczące wydajności muszą zostać uwzględnione w interfejsie API i w dokumentacji przeglądowej.

Fundamentalne zmiany

Dokumentacja dotycząca zmian przełomowych polega na tym, aby składać się z pliku najwyższego poziomu, który łączy się z poszczególnymi obszarami funkcji breaking-changes.md.

Obszar funkcji breaking-changes.md plików ma zawierać listę wszystkich znanych zmian w danym wydaniu, a także historię zmian, które były istotne w poprzednich wersjach.

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 plików breaking-changes.md zostaną zagregowane w informacjach o wersji dla każdej nowej wersji zestawu mrTK.

Wszelkie istotne zmiany, które są częścią zmiany, muszą być udokumentowane jako część żądania ściągnnięcia.

Narzędzia do edytowania znaczników 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 Docs Markdown dla Visual Studio Code — użyj klawiszy Alt+M, aby uzyskać menu opcji tworzenia dokumentów.

  • Moduł sprawdzania pisowni kodu — wyrazy z błędami pisowni zostaną podkreślone. Kliknij prawym przyciskiem myszy wyraz błędnie napisany, aby go zmienić lub zapisać w słowniku.

Oba te rozwiązania są spakowane w opublikowanym przez firmę Microsoft pakiecie Docs Authoring Pack.

Zobacz też