Przewodnik współautora witryny Microsoft Docs — omówienieMicrosoft Docs contributor guide overview

Przewodnik współautora witryny docs.microsoft.com (Docs) — Zapraszamy!Welcome to the docs.microsoft.com (Docs) Contributor Guide!

Kilka zestawów dokumentacji firmy Microsoft to zestawy typu „open source” hostowane w usłudze GitHub.Several of the Microsoft documentation sets are open source and hosted on GitHub. Nie wszystkie zestawy dokumentów działają całkowicie jako technologia typu „open source”, ale wiele ma dostępne publicznie repozytoria, w których wprowadzać sugerowane zmiany za pośrednictwem żądań ściągnięcia.Not all document sets are completely open source but many have public-facing repos where you can make suggested changes via pull requests. Takie podejście „open source” upraszcza i udoskonala komunikację między inżynierami produktu, zespołami ds. zawartości i klientami, a także oferuje inne korzyści:This open source approach streamlines and improves communication between product engineers, content teams, and customers, and has other advantages:

  • Planowanie repozytoriów typu open source w środowisku otwartym w celu uzyskiwania opinii na temat najbardziej potrzebnych dokumentów.Open source repos plan in the open to get feedback on what docs are most needed.
  • Przeglądanie repozytoriów typu „open source” w środowisku otwartym w celu publikowania najbardziej użytecznej zawartości w naszej pierwszej wersji.Open source repos review in the open to publish the most helpful content on our first release.
  • Aktualizowanie repozytoriów typu „open source” w środowisku otwartym w celu ułatwienia stałego udoskonalania zawartości.Open source repos update in the open to make it easier to continuously improve the content.

Środowisko użytkownika w witrynie docs.microsoft.com bezpośrednio integruje przepływy pracy usługi GitHub, aby jeszcze bardziej ułatwić pracę.The user experience on docs.microsoft.com integrates GitHub workflows directly to make it even easier. Rozpocznij od edytowania przeglądanego dokumentu.Start by editing the document you are viewing. Lub pomóż recenzować nowe tematy albo tworzyć opisy problemów z jakością.Or, help by reviewing new topics, or create quality issues.

Ważne

W przypadku wszystkich repozytoriów publikowanych w witrynie docs.microsoft.com stosowany jest Kodeks postępowania firmy Microsoft dotyczący rozwiązań typu open source lub Kodeks postępowania organizacji .NET Foundation.All repositories that publish to docs.microsoft.com have adopted the Microsoft Open Source Code of Conduct or the .NET Foundation Code of Conduct. Aby uzyskać więcej informacji, zobacz często zadawane pytania dotyczące kodu postępowania.For more information, see the Code of Conduct FAQ. W przypadku pytań lub komentarzy możesz też napisać na adres opencode@microsoft.com lub conduct@dotnetfoundation.org.Or contact opencode@microsoft.com, or conduct@dotnetfoundation.org with any questions or comments.

Drobne poprawki lub wyjaśnienia dotyczące dokumentacji i przykładów kodu w repozytoriach publicznych znajdują się w Warunkach korzystania z witryny docs.microsoft.com.Minor corrections or clarifications to documentation and code examples in public repositories are covered by the docs.microsoft.com Terms of Use. Nowe lub ważne zmiany powodują wygenerowanie komentarza w żądaniu ściągnięcia z prośbą o przesłanie internetowej umowy licencyjnej współautorstwa (CLA), jeśli nie jesteś pracownikiem firmy Microsoft.New or significant changes generate a comment in the pull request, asking you to submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. Zanim zrecenzujemy lub zaakceptujemy żądanie ściągnięcia, musisz wypełnić formularz online.We need you to complete the online form before we can review or accept your pull request.

Szybkie edycje istniejących dokumentówQuick edits to existing documents

Szybkie edycje usprawniają proces zgłaszania oraz naprawiania drobnych błędów i pominięć w dokumentach.Quick edits streamline the process to report and fix small errors and omissions in documents. Mimo wszelkich wysiłków drobne błędy gramatyczne i błędy pisowni przedostają się do naszych publikowanych dokumentów.Despite all efforts, small grammar and spelling errors do make their way into our published documents. Można tworzyć opisy problemów w celu zgłaszania pomyłek, ale szybszym i prostszym sposobem naprawienia błędu jest utworzenie żądania ściągnięcia, jeśli ta opcja jest dostępna.While you can create issues to report mistakes, it's faster and easier to create a pull request (PR) to fix the issue, when the option is available.

  1. Niektóre strony dokumentów umożliwiają edytowanie zawartości bezpośrednio w przeglądarce.Some docs pages allow you to edit content directly in the browser. W takiej sytuacji będzie widoczny przycisk Edytuj, taki jak pokazany poniżej.If so, you'll see an Edit button like the one shown below. Kliknięcie przycisku Edytuj (lub lokalizowanego odpowiednika) spowoduje przejście do pliku źródłowego w usłudze GitHub.Clicking the Edit (or equivalently localized) button takes you to the source file on GitHub. Jeśli nie ma przycisku Edytuj, oznacza to, że tej strony dokumentacji nie można zmieniać.If the Edit button is missing, that means the documentation page is not available to be changed.

    Lokalizacja linku Edytuj

  2. Następnie kliknij ikonę ołówka, aby edytować artykuł w pokazany sposób.Next, click the pencil icon, to edit the article as shown. Jeśli ikona ołówka jest nieaktywna, musisz zalogować się do konta usługi GitHub lub utworzyć nowe konto.If the pencil icon is grayed out, you need to either log in to your GitHub account or create a new account.

    Lokalizacja ikony ołówka

  3. Wprowadź zmiany w edytorze internetowym.Make your changes in the web editor. Kliknij kartę Podgląd zmian, aby sprawdzić formatowanie zmiany.Click the Preview changes tab to check the formatting of your change.

  4. Po wprowadzeniu zmian przewiń stronę w dół.Once you have made your changes, scroll to the bottom of the page. Wprowadź tytuł i opis zmian, a następnie kliknij pozycję Zaproponuj zmianę pliku, jak pokazano na poniższym rysunku:Enter a title and description for your changes and click Propose file change as shown in the following figure:

    Proponowanie zmiany pliku

  5. Teraz, po zaproponowaniu zmiany, musisz poprosić właścicieli repozytorium, aby „ściągnęli” Twoje zmiany do swojego repozytorium.Now that you've proposed your change, you need to ask the owners of the repository to "pull" your changes into their repository. Można to zrobić za pomocą tak zwanego „żądania ściągnięcia”.This is done using something called a "pull request". Po kliknięciu pozycji Zaproponuj zmianę pliku na powyższym rysunku, trafiasz na nową stronę, która wygląda, jak na poniższym rysunku:When you clicked on Propose file change in the figure above, you should have been taken to a new page that looks like the following figure:

    tworzenie żądania ściągnięcia

    Kliknij pozycję Utwórz żądanie ściągnięcia, wprowadź tytuł (oraz opcjonalnie opis) żądania ściągnięcia, a następnie ponownie kliknij opcję Utwórz żądanie ściągnięcia.Click Create pull request, enter a title (and optionally a description) for the pull request, and then click Create pull request again. Jeśli jesteś nowym użytkownikiem usługi GitHub, zobacz Informacje o żądaniach ściągnięcia, aby uzyskać więcej informacji.(If you are new to GitHub, see About Pull Requests for more information.)

  6. Gotowe.That's it! Członkowie zespołu ds. zawartości przejrzą i scalą żądanie ściągnięcia.Content team members will review and merge your PR. Możesz otrzymać opinię z żądaniem zmian, jeśli wprowadzono większe zmiany.You may get some feedback requesting changes if you made larger changes.

Interfejs użytkownika służący do edycji w usłudze GitHub reaguje na uprawnienia dotyczące repozytorium.The GitHub editing UI responds to your permissions on the repository. Poprzednie obrazy są dokładne w przypadku współautorów, którzy nie mają uprawnień do zapisu w repozytorium docelowym.The preceding images are accurate for contributors that do not have write permissions to the target repository. Usługa GitHub automatycznie tworzy rozwidlenie repozytorium docelowego na Twoim koncie.GitHub automatically creates a fork of the target repository in your account. Jeśli masz uprawnienia do zapisu w repozytorium docelowym, usługa GitHub tworzy nową gałąź w tym repozytorium.If you have write-access to the target repository, GitHub creates a new branch in the target repo. Nazwa gałęzi ma format <GitHubId>-patch-n korzystający z identyfikatora usługi GitHub oraz numerycznego identyfikatora gałęzi poprawki.The branch name has the form <GitHubId>-patch-n using your GitHub ID, and a numeric identifier for the patch branch.

Żądania ściągnięcia są używane dla wszystkich zmian, nawet w przypadku współautorów z dostępem do zapisu.We use pull requests for all changes, even for contributors that have write-access. Większość repozytoriów ma chronioną gałąź master, dlatego aktualizacje muszą być przesyłane jako żądania ściągnięcia.Most repositories have the master branch protected so that updates must be submitted as pull requests.

Środowisko edytowania w przeglądarce jest najlepsze w przypadku drobnych lub rzadko wprowadzanych zmian.The in-browser editing experience is best for minor or infrequent changes. Jeśli tworzysz obszerną zawartość lub używasz zaawansowanych funkcji Git (takich jak zarządzanie gałęziami i zaawansowane rozwiązywanie konfliktów scalania), musisz utworzyć rozgałęzienie repozytorium i pracować lokalnie.If you make large contributions or use advanced Git features (such as branch management or advanced merge conflict resolution), you need to fork the repo and work locally.

Uwaga

Jeśli ta opcja jest włączona, możesz edytować artykuł w dowolnym języku, po czym, zależnie od rodzaju edycji, dojdzie do następującej sytuacji:If enabled, you can edit an article in any language and, based on the type of edit, the following will happen:

  1. każda zmiana lingwistyczna, która została zaaprobowana, przyczyni się również do ulepszenia naszego aparatu tłumaczenia maszynowego;any linguistic change that is approved, will also help improve our Machine Translation engine
  2. każda edycja, która znacząco modyfikuje treść artykułu, zostanie wewnętrznie potraktowana jako źródło zmiany do tego samego artykułu w języku angielskim, dzięki czemu – jeśli zostanie zaaprobowana – zostanie ona lokalizowana we wszystkich językach.any edit that significantly modifies the content of the article will be handled internally to submit a change to the same article in English so that it will get localized in all languages if approved. Zasugerowane przez Ciebie poprawki nie tylko wpłyną pozytywnie na artykuły napisane w Twoim języku, ale również na artykuły we wszystkich dostępnych językach.Your suggested improvements will not only positively affect articles in your own language, but in all available languages.

Recenzowanie otwartych żądań ściągnięciaReview open PRs

Możesz czytać nowe tematy przed ich opublikowaniem, sprawdzając aktualnie otwarte żądania ściągnięcia.You can read new topics before they are published by checking the currently open PRs. Recenzje są zgodne z procesem przepływu usługi GitHub.Reviews follow the GitHub flow process. Proponowane aktualizacje lub nowe artykuły są widoczne w repozytoriach publicznych.You can see proposed updates or new articles in public repositories. Zapoznaj się z nimi i dodaj komentarze.Review them and add your comments. Przejrzyj nasze repozytoria dokumentów i sprawdź otwarte żądania ściągnięcia w interesujących Cię obszarach.Look at any of our docs repositories, and check the open pull requests (PRs) for areas that interest you. Opinie członków społeczności na temat proponowanych aktualizacji pomagają całej społeczności.Community feedback on proposed updates helps the entire community.

Zgłaszanie problemów z jakościąCreate quality issues

Praca nad naszymi dokumentami trwa przez cały czas.Our docs are a continuous work in progress. Dobrze opisane problemy pomagają nam skoncentrować wysiłki na obszarach najistotniejszych dla społeczności.Good issues help us focus our efforts on the highest priorities for the community. Im więcej szczegółów podasz, tym bardziej pomocny będzie opis problemu.The more detail you can provide, the more helpful the issue. Powiedz nam, jakich informacji szukano.Tell us what information you sought. Powiedz nam, których terminów wyszukiwania użyto.Tell us the search terms you used. Jeśli nie możesz rozpocząć pracy, powiedz nam, jak chcesz zacząć eksplorowanie nieznanej technologii.If you can't get started, tell us how you want to start exploring unfamiliar technology.

Wiele stron dokumentacji firmy Microsoft ma sekcję Opinie znajdującą się w dolnej części strony. Klikając w tym miejscu, można przesłać opinię dotyczącą produktu lub opinię dotyczącą zawartości, aby śledzić problemy związane z danym artykułem.Many of Microsoft's documentation pages have a Feedback section at the bottom of the page where you can click to leave Product feedback or Content feedback to track issues that are specific to that article.

Rozmowa o potrzebach rozpoczyna się od opisu problemów.Issues start the conversation about what's needed. Zespół ds. zawartości odpowie na te zgłoszenia problemów, przedstawiając pomysły dotyczące treści do dodania, i poprosi o Twoją opinię.The content team will respond to these issues with ideas for what we can add, and ask for your opinions. Po utworzeniu wersji próbnej poprosimy Cię o recenzję żądania ściągnięcia.When we create a draft, we'll ask you to review the PR.

Zwiększanie zaangażowaniaGet more involved

Inne tematy pomogą Ci w produktywny sposób rozpocząć współtworzenie zawartości witryny Microsoft Docs. Zawierają one objaśnienia dotyczące pracy z repozytoriami usługi GitHub, narzędziami języka znaczników Markdown oraz rozszerzeniami używanymi na platformie Microsoft Docs.Other topics help you get started productively contributing to Microsoft Docs. They explain working with GitHub repositories, Markdown tools, and extensions used in the Microsoft Docs platform.