Wkład w MDN Web Docs

MDN Web Docs dokumentuje platformę internetową od ponad dwunastu lat, a teraz jest przedsięwzięciem wieloplatformowym z wkładami i radą doradczą z członkami Google, Microsoft i Samsung, a także tymi reprezentującymi Firefoksa. Podstawą MDN jest to, że jest to ogromny wysiłek społeczności, w którym społeczność internetowa pomaga w tworzeniu i utrzymywaniu dokumentacji. W tym artykule podam kilka wskazówek, w jakich miejscach możesz pomóc w rozwoju MDN i jak to zrobić.

Jeśli wcześniej nie miałeś wkładu w projekt open source, MDN jest doskonałym miejscem do rozpoczęcia. Potrzebne umiejętności obejmują redagowanie tekstu, tłumaczenie z angielskiego na inne języki, umiejętności HTML i CSS do tworzenia interaktywnych przykładów lub zainteresowanie kompatybilnością przeglądarek w celu aktualizacji danych dotyczących zgodności przeglądarek. To, czego nie musisz robić, to pisać dużo kodu, aby wnieść swój wkład. Jest to bardzo proste i doskonały sposób, aby zwrócić uwagę społeczności, jeśli kiedykolwiek uznasz te dokumenty za przydatne.

Wkład w strony dokumentacji

Pierwszym miejscem, w którym możesz chcieć wnieść swój wkład, są same dokumenty MDN. MDN to wiki, więc możesz się zalogować i zacząć pomagać, poprawiając lub dodając dowolną dokumentację dotyczącą CSS, HTML, JavaScript lub dowolnej innej części platformy internetowej objętej MDN.

Aby rozpocząć edycję, musisz zalogować się za pomocą GitHub. Jak zwykle w przypadku wiki, wszyscy redaktorzy strony są wymienieni, a ta sekcja będzie używać Twojej nazwy użytkownika GitHub. Jeśli spojrzysz na którąkolwiek ze stron na liście współtwórców MDN, u dołu strony, poniższy obraz pokazuje obecnych współtwórców strony w układzie siatki CSS.

Co możesz edytować?

Rzeczy, które możesz rozważyć jako redaktor, to naprawianie oczywistych literówek i błędów gramatycznych. Jeśli jesteś dobrym korektorem i redaktorem, możesz poprawić czytelność dokumentów, poprawiając wszelkie błędy ortograficzne lub inne, które zauważysz.

Możesz również zauważyć błąd techniczny lub miejsce, w którym zmieniły się specyfikacje i gdzie przydatne byłyby aktualizacje lub wyjaśnienia. Dzięki ogromnej gamie funkcji platform internetowych objętych MDN i szybkości zmian, bardzo łatwo jest coś stracić z aktualności, jeśli coś zauważysz - napraw to!

Być może będziesz w stanie wykorzystać określoną wiedzę, którą musisz, aby dodać dodatkowe informacje. Na przykład Eric Bailey dodaje do wielu stron sekcje dotyczące kwestii dostępności. Jest to genialny wysiłek, aby podkreślić rzeczy, o których powinniśmy myśleć, korzystając z określonej rzeczy.

Innym miejscem, które możesz dodać do strony, jest dodawanie linków „Zobacz też”. Mogą to być łącza do innych części MDN lub do zasobów zewnętrznych. Przy dodawaniu zasobów zewnętrznych powinny one być wysoce związane z właściwością, elementem lub techniką opisaną w tym dokumencie. Dobrym kandydatem byłby samouczek pokazujący, jak korzystać z tej funkcji, coś, co dałoby czytelnikowi poszukującemu informacji wartościowy kolejny krok.

Jak edytować dokument?

Po zalogowaniu zobaczysz link do Edytuj na stronach w MDN, kliknięcie tego spowoduje przejście do edytora WYSIWYG do edycji treści. Twoje pierwsze kilka zmian prawdopodobnie będzie drobnymi zmianami, w takim przypadku powinieneś być w stanie podążać za swoim nosem i edytować tekst. Jeśli wprowadzasz obszerne zmiany, warto najpierw zajrzeć do przewodnika po stylu. Dostępny jest również przewodnik dotyczący korzystania z edytora WYSIWYG.

Po dokonaniu edycji możesz wyświetlić podgląd, a następnie opublikować. Przed publikacją dobrze jest wyjaśnić, co dodałeś i dlaczego używasz pola Komentarz do wersji.

Tłumaczenia językowe

Ci z nas, dla których angielski jest pierwszym językiem, są niezwykle szczęśliwi, jeśli chodzi o informacje w sieci, ponieważ są w stanie uzyskać prawie wszystkie informacje, których moglibyśmy kiedykolwiek chcieć w naszym własnym języku. Jeśli jesteś w stanie przetłumaczyć strony w języku angielskim na inne języki, możesz pomóc w tłumaczeniu dokumentów MDN Web Docs, udostępniając wszystkie te informacje większej liczbie osób.

Jeśli klikniesz ikonę języka na dowolnej stronie, możesz zobaczyć, na jakie języki zostały przetłumaczone informacje, i możesz dodać własne tłumaczenia zgodnie z informacjami na stronie Tłumaczenie stron MDN.

Przykłady interaktywne

Interaktywne przykłady w MDN to przykłady, które zobaczysz na górze wielu stron MDN, na przykład ta dla właściwości grid-area .

Te przykłady pozwalają odwiedzającym MDN wypróbować różne wartości właściwości CSS lub wypróbować funkcję JavaScript bezpośrednio w MDN bez konieczności przechodzenia do środowiska programistycznego, aby to zrobić. Projekt dodania tych przykładów trwa już od około roku, o projekcie i dotychczasowych postępach można przeczytać w poście Wprowadzanie interaktywnych przykładów do MDN.

Treść tych interaktywnych przykładów jest przechowywana w repozytorium interaktywnych przykładów na GitHub. Na przykład, jeśli chcesz zlokalizować przykład dla obszaru siatki, znajdziesz go w tym repozytorium pod live-examples/css-examples/grid . W tym folderze znajdziesz dwa pliki grid-area , plik HTML i plik CSS.

grid-area.html

 <section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>

grid.obszar.css

 .example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }

Przykład interaktywny to tylko małe demo, które wykorzystuje kilka standardowych klas i identyfikatorów, aby framework mógł pobrać przykład i uczynić go interaktywnym, gdzie wartości mogą być zmieniane przez odwiedzającego stronę, który chce szybko zobaczyć, jak to działa Pracuje. Aby dodać lub edytować przykład interaktywny, najpierw rozwidlej repozytorium przykładów interaktywnych, sklonuj je na swój komputer i postępuj zgodnie z instrukcjami na stronie Współtworzenie, aby zainstalować wymagane pakiety z npm i mieć możliwość lokalnego tworzenia i testowania przykładów.

Następnie utwórz oddział i edytuj lub utwórz nowy przykład. Gdy będziesz z niego zadowolony, wyślij Pull Request do repozytorium Interaktywnych przykładów, aby poprosić o przejrzenie Twojego przykładu. Aby zachować spójność przykładów, recenzje są dość niepewne, ale powinny wyraźnie wskazywać na zmiany, które należy wprowadzić, aby można było zaktualizować przykład i zlecić jego zatwierdzenie, połączenie i dodanie do strony MDN.

Mając już omówiony prawie cały CSS (oprócz przykładów JavaScript), MDN szuka teraz pomocy w tworzeniu przykładów HTML. W poście na Forum Dyskursowym MDN znajdują się instrukcje, jak zacząć. Sprawdź ten post, ponieważ zawiera linki do dokumentu Google, którego możesz użyć, aby wskazać, że pracujesz nad konkretnym przykładem, a także kilka innych przydatnych informacji.

Interaktywne przykłady są niezwykle przydatne dla osób eksplorujących platformę internetową, więc dodanie do projektu jest doskonałym sposobem na wniesienie wkładu. Tworzenie przykładów CSS lub HTML wymaga znajomości CSS i HTML, a także umiejętności wymyślenia jasnej demonstracji. Ten ostatni punkt jest często najtrudniejszy. Stworzyłem wiele interaktywnych przykładów CSS i spędziłem więcej czasu na wymyślaniu najlepszego przykładu dla każdej właściwości niż na pisanie kodu.

Dane zgodne z przeglądarką

Dość niedawno dane dotyczące zgodności przeglądarek wymienione na stronach MDN zaczęły być aktualizowane w ramach projektu zgodności przeglądarek. W ramach tego projektu opracowywane są dane dotyczące kompatybilności przeglądarek w formacie JSON, które mogą wyświetlać tabele kompatybilności w MDN, ale także mogą być przydatnymi danymi do innych celów.

Dane dotyczące zgodności przeglądarek znajdują się w serwisie GitHub, a jeśli znajdziesz stronę, która zawiera nieprawidłowe informacje lub nadal korzysta ze starych tabel, możesz przesłać żądanie ściągnięcia. Repozytorium zawiera informacje o wkładzie, jednak najprostszym sposobem na rozpoczęcie jest edycja istniejącego przykładu. Niedawno zaktualizowałem informacje dotyczące właściwości CSS shape-outside . Właściwość miała już pewne dane w nowym formacie, ale były niekompletne i nieprawidłowe.

Aby edytować te dane, najpierw rozwidłem dane dotyczące kompatybilności przeglądarki, aby mieć własny widelec. Następnie sklonowałem to na moim komputerze i utworzyłem nową gałąź, w której wprowadzam zmiany.

Kiedy już miałem nową gałąź, znalazłem plik JSON dla shape-outside i mogłem wprowadzać zmiany. Miałem już dobry pomysł na obsługę usługi przez przeglądarkę; Użyłem również przykładu na żywo na stronie MDN z kształtami zewnętrznymi, aby przetestować wsparcie, gdy nie byłem pewien. W związku z tym dokonywanie zmian polegało na przepracowaniu pliku, sprawdzeniu podanych numerów wersji pod kątem obsługi właściwości i zaktualizowaniu tych, które były nieprawidłowe.

Ponieważ plik jest w formacie JSON, można go dość łatwo edytować w dowolnym edytorze tekstu. Plik .editorconfig wyjaśnia proste reguły formatowania dla tych dokumentów. Na tej liście kontrolnej znajduje się również kilka pomocnych wskazówek.

Po wprowadzeniu zmian możesz je zatwierdzić, przenieść gałąź do swojego forka, a następnie wykonać pull request do repozytorium danych zgodnych z przeglądarką. Jest prawdopodobne, że podobnie jak w przypadku przykładów na żywo, recenzent będzie musiał wprowadzić pewne zmiany. W moim PR dla danych Shapes miałem kilka błędów w sposobie, w jaki oznaczyłem dane i musiałem wprowadzić pewne zmiany w linkach. Te były proste do wykonania, a potem mój PR został połączony.

Zaczynaj

Możesz zacząć od wybrania czegoś do dodania i w wielu przypadkach rozpoczęcia pracy nad tym. Jeśli masz jakieś pytania lub potrzebujesz pomocy, to forum MDN Discourse jest dobrym miejscem do publikowania. MDN to miejsce, do którego udaję się w poszukiwaniu informacji, do którego wysyłam zarówno nowych programistów, jak i doświadczonych programistów, a jego siłą jest fakt, że wszyscy możemy pracować, aby to ulepszyć.

Jeśli nigdy wcześniej nie robiłeś pull requesta w projekcie, jest to bardzo przyjazne miejsce na zrobienie tego pierwszego PR i, jak mam nadzieję, pokazałem, istnieją sposoby, które nie wymagają pisania żadnego kodu. Bardzo cenną umiejętnością w każdym projekcie dokumentacji jest umiejętność pisania, edytowania i tłumaczenia, ponieważ te umiejętności mogą sprawić, że dokumentacja techniczna będzie łatwiejsza do czytania i dostępna dla większej liczby osób na całym świecie.