Współtworzenia dokumentacji dla deweloperów rzeczywistości mieszanej

Witamy w publicznym repozytorium dla deweloperów rzeczywistości mieszanej! Wszystkie artykuły tworzone lub edytowane w tym repozytorium będą widoczne dla opinii publicznej.

Dokumentacja rzeczywistości mieszanej jest teraz hostowana w witrynie Microsoft Learn, która używa języka Markdown o smaku gitHub z funkcjami języka Markdig. Zawartość edytowana w tym repozytorium jest sformatowana w stylizowane strony, które są wyświetlane na stronie /windows/mixed-reality.

Na tej stronie opisano podstawowe kroki i wskazówki dotyczące współtworzenia oraz linki do podstaw języka Markdown. Dziękujemy za Twój wkład!

Dostępne repozytoria

Nazwa repozytorium	URL
Azure Remote Rendering	MicrosoftDocs/azure-docs/articles/remote-rendering
HoloLens	MicrosoftDocs/HoloLens
Rzeczywistość mieszana	MicrosoftDocs/rzeczywistość mieszana
Przewodnik entuzjastów VR	MicrosoftDocs/mixed-reality/enthusiast-guide

Przed rozpoczęciem

Jeśli jeszcze go nie masz, musisz utworzyć konto usługi GitHub.

Uwaga

Jeśli jesteś pracownikiem firmy Microsoft, połącz swoje konto GitHub z aliasem firmy Microsoft w portalu open source firmy Microsoft. Dołącz do organizacji "Microsoft" i "MicrosoftDocs".

Podczas konfigurowania konta usługi GitHub zalecamy również stosowanie następujących środków ostrożności:

• Utwórz silne hasło dla konta usługi Github.
• Włącz uwierzytelnianie dwuskładnikowe.
• Zapisz kody odzyskiwania w bezpiecznym miejscu.
• Zaktualizuj ustawienia profilu publicznego.
  • Ustaw swoją nazwę i rozważ ustawienie publicznej poczty e-mail na Nie pokazuj mojego adresu e-mail.
  • Zalecamy przekazanie obrazu profilu, ponieważ miniatura jest wyświetlana na stronach dokumentacji, do których współtworzysz.
• Jeśli planujesz używać wiersza polecenia, rozważ skonfigurowanie menedżera poświadczeń Git dla systemu Windows. W ten sposób nie trzeba wprowadzać hasła za każdym razem, gdy tworzysz wkład.

System publikowania jest powiązany z usługą GitHub, dlatego te kroki są ważne. Zostaniesz wymieniony jako autor lub współautor każdego artykułu przy użyciu aliasu usługi GitHub.

Edytowanie istniejącego artykułu

Użyj następującego przepływu pracy, aby zaktualizować istniejący artykuł za pośrednictwem usługi GitHub w przeglądarce internetowej:

1. Przejdź do artykułu, który chcesz edytować w folderze "mixed-reality-docs".

2. Wybierz przycisk edycji (ikona ołówka) w prawym górnym rogu, co spowoduje automatyczne rozwidlenie gałęzi jednorazowej z gałęzi "master".

   

3. Edytuj zawartość artykułu zgodnie z "Podstawy języka Markdown".

4. Zaktualizuj metadane w górnej części każdego artykułu:

   • title: tytuł strony wyświetlany na karcie przeglądarki po wyświetleniu artykułu. Tytuły stron są używane do seo i indeksowania, więc nie zmieniaj tytułu, chyba że jest to konieczne (choć jest to mniej krytyczne przed upublicznienie dokumentacji).
   • opis: Napisz krótki opis zawartości artykułu, który zwiększa SEO i odnajdywanie.
   • author: Jeśli jesteś głównym właścicielem strony, dodaj tutaj alias usługi GitHub.
   • ms.author: Jeśli jesteś głównym właścicielem strony, dodaj tutaj alias firmy Microsoft (nie potrzebujesz @microsoft.comtylko aliasu).
   • ms.date: Zaktualizuj datę, jeśli dodasz główną zawartość do strony, ale nie w przypadku poprawek, takich jak wyjaśnienie, formatowanie, gramatyka lub pisownia.
   • keywords: Słowa kluczowe pomagają w optymalizacji wyszukiwarek (optymalizacja aparatu wyszukiwania). Dodaj słowa kluczowe oddzielone przecinkami i spacją, które są specyficzne dla artykułu, ale nie są znakiem interpunkcyjnym po ostatnim słowie kluczowym na liście. Nie musisz dodawać globalnych słów kluczowych, które mają zastosowanie do wszystkich artykułów, ponieważ są one zarządzane gdzie indziej.

5. Po zakończeniu edycji artykułu przewiń w dół i wybierz pozycję Zaproponuj zmianę pliku.

6. Na następnej stronie wybierz pozycję Utwórz żądanie ściągnięcia, aby scalić automatycznie utworzoną gałąź z gałęzią "master".

7. Powtórz powyższe kroki dla następnego artykułu, który chcesz edytować.

Zmiana nazwy lub usunięcie istniejącego artykułu

Jeśli zmiana zmieni nazwę lub usunie istniejący artykuł, pamiętaj, aby dodać przekierowanie. W ten sposób każda osoba mająca link do istniejącego artykułu nadal znajdzie się we właściwym miejscu. Przekierowania są zarządzane przez plik .openpublishing.redirection.json w katalogu głównym repozytorium.

Aby dodać przekierowanie do .openpublishing.redirection.json, dodaj wpis do tablicy redirections :

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}

• Jest source_path to względna ścieżka repozytorium do starego artykułu, który usuwasz. Upewnij się, że ścieżka zaczyna się od mixed-reality-docs i kończy się ciągiem .md.
• Jest redirect_url to względny publiczny adres URL ze starego artykułu do nowego artykułu. Upewnij się, że ten adres URL nie zawiera mixed-reality-docs adresu LUB .md, ponieważ odwołuje się do publicznego adresu URL, a nie ścieżki repozytorium. Łączenie z sekcją w nowym artykule przy użyciu #section jest dozwolone. W razie potrzeby możesz również użyć ścieżki bezwzględnej do innej witryny.
• redirect_document_id wskazuje, czy chcesz zachować identyfikator dokumentu z poprzedniego pliku. Wartość domyślna to false. Użyj true polecenia , jeśli chcesz zachować wartość atrybutu ms.documentid z przekierowanego artykułu. Jeśli zachowasz identyfikator dokumentu, dane, takie jak widoki stron i rankingi, zostaną przeniesione do artykułu docelowego. Zrób to, jeśli przekierowanie jest przede wszystkim zmianą nazwy, a nie wskaźnikiem do innego artykułu, który obejmuje tylko część tej samej zawartości.

Jeśli dodasz przekierowanie, pamiętaj o usunięciu starego pliku.

Tworzenie nowego artykułu

Użyj następującego przepływu pracy, aby utworzyć nowe artykuły w repozytorium dokumentacji za pośrednictwem usługi GitHub w przeglądarce internetowej:

1. Utwórz rozwidlenie od gałęzi "master" microsoftDocs/mixed-reality (za pomocą przycisku Rozwidlenie w prawym górnym rogu).

   

2. W folderze "mixed-reality-docs" wybierz pozycję Utwórz nowy plik w prawym górnym rogu.

3. Utwórz nazwę strony artykułu (użyj łączników zamiast spacji i nie używaj interpunkcji ani apostrofów) i dołącz ".md"

   

   Ważne

   Upewnij się, że utworzono nowy artykuł z folderu "mixed-reality-docs". Możesz to potwierdzić, sprawdzając ciąg "/mixed-reality-docs/" w nowym wierszu nazwy pliku.

4. W górnej części nowej strony dodaj następujący blok metadanych:

   ---
   title:
   description:
   author:
   ms.author:
   ms.date:
   ms.topic: article
   keywords:
   ---
   

5. Wypełnij odpowiednie pola metadanych zgodnie z instrukcjami w powyższej sekcji.

6. Pisanie zawartości artykułu przy użyciu podstaw języka Markdown.

7. Dodaj sekcję ## See also w dolnej części artykułu z linkami do innych odpowiednich artykułów.

8. Po zakończeniu wybierz pozycję Zatwierdź nowy plik.

9. Wybierz pozycję Nowe żądanie ściągnięcia i scal gałąź "master" rozwidlenia z gałęzią MicrosoftDocs/mixed-reality "master" (upewnij się, że strzałka wskazuje prawidłowy sposób).

   

Podstawy języka znaczników markdown

Następujące zasoby pomogą Ci dowiedzieć się, jak edytować dokumentację przy użyciu języka Markdown:

• Podstawy języka Markdown
• Plakat referencyjny języka Markdown na pierwszy rzut oka
• Dodatkowe zasoby do pisania języka Markdown dla platformy Microsoft Learn

Dodawanie tabel

Ze względu na sposób, w jaki tabele stylów dokumentacji technicznej firmy Microsoft nie będą miały obramowania ani stylów niestandardowych, nawet jeśli wypróbujesz wbudowany kod CSS. Wydaje się, że będzie działać przez krótki okres czasu, ale ostatecznie platforma usunie styl z tabeli. Więc zaplanuj z wyprzedzeniem i zachowaj proste tabele. Oto witryna, która ułatwia tabele języka Markdown.

Rozszerzenie Języka Markdown witryny Docs dla programu Visual Studio Code ułatwia również generowanie tabel, jeśli używasz programu Visual Studio Code (zobacz poniżej) do edytowania dokumentacji.

Dodawanie obrazów

Musisz przekazać obrazy do folderu "mixed-reality-docs/images" w repozytorium, a następnie odwołać się do nich odpowiednio w artykule. Obrazy będą automatycznie wyświetlane w pełnym rozmiarze, co oznacza, że duże obrazy wypełnią całą szerokość artykułu. Zalecamy wstępne ustalanie rozmiaru obrazów przed ich przekazaniem. Zalecana szerokość wynosi od 600 do 700 pikseli, chociaż rozmiar powinien być większy lub wyłączony, jeśli jest to gęsty zrzut ekranu lub ułamek zrzutu ekranu, odpowiednio.

Ważne

Obrazy można przekazywać tylko do rozwidlenia przed scaleniem. Jeśli więc planujesz dodawanie obrazów do artykułu, musisz najpierw dodać obrazy do folderu "images" rozwidlenia lub upewnić się, że wykonano następujące czynności w przeglądarce internetowej:

1. Rozwidlenie repozytorium MicrosoftDocs/mixed-reality.
2. Edytowano artykuł w rozwidleniu.
3. Przekazano obrazy, do których odwołujesz się w artykule, do folderu "mixed-reality-docs/images" w rozwidleniu.
4. Utworzono żądanie ściągnięcia w celu scalenia rozwidlenia z gałęzią "master" microsoftDocs/mixed-reality.

Aby dowiedzieć się, jak skonfigurować własne rozwidlenie repozytorium, postępuj zgodnie z instrukcjami dotyczącymi tworzenia nowego artykułu.

Wyświetlanie podglądu pracy

Podczas edytowania w usłudze GitHub za pośrednictwem przeglądarki internetowej możesz wybrać kartę Podgląd w górnej części strony, aby wyświetlić podgląd pracy przed zatwierdzeniem.

Uwaga

Podgląd przygotowanych zmian jest dostępny tylko dla pracowników firmy Microsoft

Pracownicy firmy Microsoft: po scaleniu kontrybucji z gałęzią "main" możesz przejrzeć zawartość, zanim przejdzie ona do publicznej wiadomości w katalogu /windows/mixed-reality?branch=main. Znajdź artykuł przy użyciu spisu treści w lewej kolumnie.

Edytowanie w przeglądarce a edytowanie przy użyciu klienta klasycznego

Edytowanie w przeglądarce jest najprostszym sposobem wprowadzania szybkich zmian, jednak istnieje kilka wad:

• Nie uzyskujesz sprawdzania pisowni.
• Nie uzyskujesz żadnych inteligentnych linków do innych artykułów (musisz ręcznie wpisać nazwę pliku artykułu).
• Przekazywanie i odwoływanie się do obrazów może być kłopotliwe.

Jeśli nie chcesz radzić sobie z tymi problemami, użyj klienta klasycznego, takiego jak Visual Studio Code , z kilkoma pomocnymi rozszerzeniami podczas współtworzenia.

Korzystanie z programu Visual Studio Code

Z powodów wymienionych powyżej możesz użyć klienta klasycznego do edytowania dokumentacji zamiast przeglądarki internetowej. Zalecamy używanie programu Visual Studio Code.

Ustawienia

Wykonaj następujące kroki, aby skonfigurować program Visual Studio Code do pracy z tym repozytorium:

1. W przeglądarce internetowej:
   1. Zainstaluj narzędzie Git dla komputera.
   2. Zainstalowanie programu Visual Studio Code.
   3. Rozwidlenie MicrosoftDocs/rzeczywistości mieszanej, jeśli jeszcze tego nie zrobiono.
   4. W rozwidleniu wybierz pozycję Klonuj lub pobierz i skopiuj adres URL.
2. Utwórz lokalny klon rozwidlenia w programie Visual Studio Code:
   1. Z menu Widok wybierz pozycję Paleta poleceń.
   2. Wpisz "Git: Clone".
   3. Wklej skopiowany adres URL.
   4. Wybierz miejsce zapisania klonu na komputerze.
   5. Wybierz pozycję Otwórz repozytorium w oknie podręcznym.

Edytowanie dokumentacji

Użyj następującego przepływu pracy, aby wprowadzić zmiany w dokumentacji za pomocą programu Visual Studio Code:

Uwaga

Wszystkie wskazówki dotyczące edytowania i tworzenia artykułów oraz podstawy edytowania języka Markdown z powyższych elementów mają zastosowanie również podczas korzystania z programu Visual Studio Code.

1. Upewnij się, że sklonowany rozwidlenie jest aktualne w oficjalnym repozytorium.

   1. W przeglądarce internetowej utwórz żądanie ściągnięcia, aby zsynchronizować ostatnie zmiany z innych współautorów w dokumencie MicrosoftDocs/mixed-reality "master" do rozwidlenia (upewnij się, że strzałka wskazuje właściwy sposób).

      

   2. W programie Visual Studio Code wybierz przycisk synchronizacji, aby zsynchronizować świeżo zaktualizowane rozwidlenie z klonem lokalnym.

      

2. Tworzenie lub edytowanie artykułów w sklonowanym repozytorium przy użyciu programu Visual Studio Code.

   1. Edytuj co najmniej jeden artykuł (w razie potrzeby dodaj obrazy do folderu "images").

   2. Zapisz zmiany w Eksploratorze.

      

   3. Zatwierdź wszystkie zmiany w kontroli źródła (po wyświetleniu monitu napisz komunikat zatwierdzenia).

      

   4. Wybierz przycisk synchronizacji, aby zsynchronizować zmiany z powrotem do źródła (rozwidlenie w usłudze GitHub).

      

3. W przeglądarce internetowej utwórz żądanie ściągnięcia, aby zsynchronizować nowe zmiany w rozwidleniu z powrotem do dokumentów MicrosoftDocs/mixed-reality "master" (upewnij się, że strzałka wskazuje prawidłowy sposób).

   

Przydatne rozszerzenia

Podczas edytowania dokumentacji przydatne są następujące rozszerzenia programu Visual Studio Code:

• Rozszerzenie Języka Markdown witryny Docs dla programu Visual Studio Code — użyj Alt+M , aby wyświetlić menu opcji tworzenia dokumentów, takich jak:
  • Przeszukaj przekazane obrazy i odwoływanie się do tych obrazów.
  • Dodaj formatowanie, takie jak listy, tabele i objaśnienie specyficzne dla dokumentów, takie jak >[!NOTE].
  • Wyszukaj i odwołuj się do wewnętrznych linków i zakładek (linki do określonych sekcji na stronie).
  • Błędy formatowania są wyróżnione (umieść wskaźnik myszy na błędzie, aby dowiedzieć się więcej).
• 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.