Udostępnij za pośrednictwem

Jak współtworzyć dokumentację programu SQL Server

  • Artykuł

Dotyczy:programu SQL ServerAzure SQL DatabaseAzure Synapse AnalyticsAnalytics Platform System (PDW)

Każda osoba może współtworzyć dokumentację programu SQL Server. Obejmuje to poprawianie literówek, sugerowanie lepszych wyjaśnień i poprawę dokładności technicznej. W tym artykule wyjaśniono, jak rozpocząć pracę z zawartością i jak działa proces.

Istnieją dwa główne przepływy pracy, których można użyć do współtworzenia:

Przepływ pracy Opis
Edytuj w przeglądarce Dobre dla małych, szybkich edycji dowolnego artykułu.
edytuj lokalnie za pomocą narzędzi Dobre dla bardziej złożonych edycji, edycji obejmujących wiele artykułów oraz częstych kontrybucji.

Zespół ds. zawartości SQL weryfikuje wszystkie publiczne wkłady w celu zapewnienia dokładności i spójności technicznej.

Edytuj w przeglądarce

Możesz wprowadzić proste zmiany w zawartości programu SQL Server w przeglądarce, a następnie przesłać je do firmy Microsoft. Aby uzyskać więcej informacji, zobacz omówienie przewodnika dla współautorów .

Poniżej przedstawiono podsumowanie procesu:

  1. Na stronie, o której masz opinię, wybierz ikonę ołówka w prawym górnym rogu.
  2. Na następnej stronie wybierz ikonę Ołówek w prawym górnym rogu. Jeśli ta ikona nie jest wyświetlana, może być konieczne najpierw zalogowanie się do konta usługi GitHub.
  3. Na następnej stronie, w oknie tekstu Edytuj plik, wprowadź zmiany bezpośrednio w tekście, który chcesz zmienić. Jeśli potrzebujesz pomocy przy formatowaniu nowego lub zmienionego tekstu, zobacz Ściągawka języka Markdown.
  4. Po wprowadzeniu zmian, w sekcji Zatwierdź zmiany:
    1. W pierwszym polu tekstowym wprowadź krótki opis wprowadzonej zmiany.
    2. W polu Dodaj opis rozszerzony (opcjonalny), podaj krótkie wyjaśnienie swojej zmiany.
  5. Wybierz pozycję Zaproponuj zmianę pliku.
  6. Na stronie Porównanie zmian wybierz pozycję Utwórz żądanie ściągnięcia.
  7. Na stronie Otwórz żądanie ściągnięcia wybierz pozycję Utwórz żądanie ściągnięcia.

Poniższy plik GIF przedstawia kompleksową procedurę przesyłania zmian w przeglądarce:

zrzut ekranu przedstawiający edytowanie dokumentów SQL.

Edytuj lokalnie za pomocą narzędzi

Inną opcją edycji jest sforkowanie repozytoriów sql-docs lub azure-docs i sklonowanie ich lokalnie na swoim komputerze. Następnie możesz przesłać zmiany za pomocą edytora Markdown i klienta git. Ten przepływ pracy jest dobry w przypadku edycji, które są bardziej złożone lub obejmują wiele plików. Jest również dobrym rozwiązaniem dla częstych współautorów dokumentacji technicznej firmy Microsoft.

Aby wspierać ten sposób, zapoznaj się z następującymi artykułami:

Jeśli prześlesz żądanie scalenia z istotnymi zmianami w dokumentacji, otrzymasz komentarz w serwisie GitHub z prośbą o przesłanie Umowy Licencyjnej dla Współtwórców (CLA) online . Aby można było zaakceptować żądanie ściągnięcia, musisz wypełnić formularz online.

Uznanie

Jeśli zmiany zostaną zaakceptowane, jesteś uznawany za współautora w górnej części artykułu.

Zrzut ekranu przedstawiający rozpoznawanie zawartości.

Omówienie dokumentacji SQL

Ta sekcja zawiera więcej wskazówek dotyczących pracy w repozytorium sql-docs.

Ważny

Informacje w tej sekcji dotyczą sql-docs. Jeśli edytujesz artykuł SQL w dokumentacji platformy Azure, zobacz pliku Readme dla repozytorium azure-docs w witrynie GitHub.

Repozytorium sql-docs używa kilku folderów standardowych do organizowania zawartości.

Folder Opis
dokumentacji Zawiera całą opublikowaną zawartość programu SQL Server. Podfoldery logicznie organizują różne obszary zawartości.
docs/includes Zawiera pliki dołączane. Te pliki to bloki zawartości, które mogą być zawarte w co najmniej jednym innym artykule.
./media Każdy folder może mieć jeden podfolder media dla obrazów artykułów. Folder media z kolei zawiera podfoldery o tej samej nazwie co artykuły wyświetlane na obrazie. Obrazy powinny być plikami .png zapisanymi małymi literami i bez spacji.
TOC.MD Plik spisu treści. Każdy podfolder ma opcję użycia jednego pliku TOC.MD.

"Dotyczy następujących"

Każdy artykuł dotyczący SQL Server zawiera plik dołączający applies-to umieszczony po tytule. Wskazuje to, do jakich obszarów lub wersji programu SQL Server ma zastosowanie artykuł.

Rozważmy następujący przykład języka Markdown, który ściąga plik dołączania applies-to-version/sql-asdb-asa-pdw.md.

[!INCLUDE [SQL Server Azure SQL Database Synapse Analytics PDW](../includes/applies-to-version/sql-asdb-asdbmi-asa-pdw.md)]

Spowoduje to dodanie następującego tekstu w górnej części artykułu:

zrzut ekranu przedstawiający pozycję Dotyczy tekstu.

Aby znaleźć poprawne zastosowanie do pliku dołączania do artykułu, skorzystaj z następujących wskazówek:

  • Aby zapoznać się z listą często używanych plików dołączanych dotyczących wersjonowania i zastosowań, zobacz pliki dołączane SQL Server dla wersjonowania i zastosowań.
  • Zapoznaj się z innymi artykułami, które obejmują tę samą funkcję lub powiązane zadanie. Jeśli edytujesz ten artykuł, możesz skopiować link 'applies-to include' w formacie Markdown (możesz anulować edycję bez przesyłania).
  • Przeszukaj katalog docs/includes pod kątem plików zawierających tekst applies-to. Aby szybko filtrować, możesz użyć przycisku Znajdź w usłudze GitHub. Wybierz plik, aby zobaczyć, jak jest renderowany.
  • Zwróć uwagę na konwencję nazewnictwa. Jeśli nazwa zawiera wiele znaków x w ciągu tekstu, zwykle są stosowane jako symbole zastępcze wskazujące na brak wsparcia dla usługi. Na przykład appliesto-xx-xxxx-asdw-xxx-md.md wskazuje wsparcie wyłącznie dla Azure Synapse Analytics, ponieważ tylko asdw jest wypisana, podczas gdy inne pola mają x.
  • Niektóre z nich zawierają określenie numeru wersji, takiego jak tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md. Używaj tych plików dołączanych tylko wtedy, gdy wiesz, że funkcja została wprowadzona z określoną wersją programu SQL Server.

Zasoby współautora

  • Przewodnik dla współtwórcy
  • przewodnik po stylu firmy Microsoft
  • podstawy języka Markdown

Napiwek

Jeśli masz uwagi dotyczące produktu, a nie dokumentacji, przekaż je tutaj na temat produktu SQL Server.

Powiązana zawartość

Zapoznaj się z repozytorium sql-docs w usłudze GitHub.

Znajdź artykuł, prześlij zmianę i pomóż społeczności programu SQL Server.

Dziękuję.