Contribuția la MDN Web Docs

MDN Web Docs documentează platforma web de peste doisprezece ani și este acum un efort multiplatform cu contribuții și un comitet consultativ cu membri de la Google, Microsoft și Samsung, precum și cei care reprezintă Firefox. Ceva care este fundamental pentru MDN este că este un efort uriaș al comunității, comunitatea web ajutând la crearea și menținerea documentației. În acest articol, vă voi oferi câteva indicații cu privire la locurile în care puteți contribui la MDN și exact cum să faceți acest lucru.

Dacă nu ați contribuit până acum la un proiect open source, MDN este un loc genial de început. Abilitățile necesare variază de la editare, traducere din engleză în alte limbi, abilități HTML și CSS pentru crearea de exemple interactive sau interes pentru compatibilitatea browserului pentru actualizarea datelor de compatibilitate a browserului. Ceea ce nu trebuie să faceți este să scrieți o mulțime de cod pentru a contribui. Este foarte simplu și o modalitate excelentă de a da înapoi comunității dacă ați găsit vreodată aceste documente utile.

Contribuția la paginile de documentare

Primul loc în care ați putea dori să contribui este documentele MDN în sine. MDN este un wiki, așa că puteți să vă conectați și să începeți să ajutați prin corectarea sau adăugarea oricărei documentații pentru CSS, HTML, JavaScript sau oricare dintre celelalte părți ale platformei web acoperite de MDN.

Pentru a începe editarea, trebuie să vă conectați folosind GitHub. Așa cum este de obicei în cazul unui wiki, sunt listați toți editorii unei pagini, iar această secțiune va folosi numele dvs. de utilizator GitHub. Dacă vă uitați la oricare dintre paginile din MDN, contribuatorii sunt listați în partea de jos a paginii, imaginea de mai jos arată colaboratorii actuali ai paginii cu CSS Grid Layout.

Ce ai putea edita?

Lucrurile pe care le-ați putea lua în considerare în calitate de editor sunt remedierea greșelilor de scriere și a erorilor gramaticale evidente. Dacă sunteți un bun corector și corector, atunci este posibil să puteți îmbunătăți lizibilitatea documentelor prin remedierea oricăror erori de ortografie sau a altor erori pe care le observați.

De asemenea, este posibil să observați o eroare tehnică sau unde specificațiile s-au schimbat și unde ar fi utilă o actualizare sau o clarificare. Cu gama uriașă de caracteristici ale platformei web acoperite de MDN și rata de schimbare, este foarte ușor ca lucrurile să iasă din actualitate, dacă observați ceva - remediați-l!

Este posibil să puteți utiliza anumite cunoștințe specifice pe care le aveți pentru a adăuga informații suplimentare. De exemplu, Eric Bailey a adăugat secțiuni privind problemele de accesibilitate în multe pagini. Acesta este un efort genial de a evidenția lucrurile la care ar trebui să ne gândim când folosim un anumit lucru.

Un alt loc pe care l-ați putea adăuga la o pagină este adăugarea de linkuri „Vezi și”. Acestea ar putea fi link-uri către alte părți ale MDN sau către resurse externe. Atunci când se adaugă resurse externe, acestea ar trebui să fie foarte relevante pentru proprietatea, elementul sau tehnica descrise de acel document. Un candidat bun ar fi un tutorial care demonstrează cum să folosești această funcție, ceva care ar oferi unui cititor care caută informații un pas valoros următor.

Cum se editează un document?

Odată ce v-ați autentificat, veți vedea un link către Editare pe paginile din MDN, făcând clic pe acesta, veți ajunge într-un editor WYSIWYG pentru editarea conținutului. Este posibil ca primele modificări ale dvs. să fie mici modificări, caz în care ar trebui să vă puteți urmări nasul și să editați textul. Dacă faceți modificări extinse, atunci ar merita să aruncați o privire mai întâi la ghidul de stil. Există, de asemenea, un ghid pentru utilizarea Editorului WYSIWYG.

După ce ați efectuat editarea, puteți să previzualizați și apoi să publicați. Înainte de publicare, este o idee bună să explicați ce ați adăugat și de ce utilizând câmpul Comentariu revizuire.

Traduceri de limbi

Aceia dintre noi cu limba engleză ca primă limbă suntem incredibil de norocoși când vine vorba de informații de pe web, fiind capabili să obținem aproape toate informațiile pe care le-am putea dori vreodată în propria noastră limbă. Dacă puteți traduce pagini în limba engleză în alte limbi, atunci puteți ajuta la traducerea MDN Web Docs, făcând toate aceste informații disponibile pentru mai multe persoane.

Dacă faceți clic pe pictograma limbii de pe orice pagină, puteți vedea în ce limbi au fost traduse informațiile respective și puteți adăuga propriile traduceri urmând informațiile de pe pagina Traducerea paginilor MDN.

Exemple interactive

Exemplele interactive pe MDN sunt exemplele pe care le veți vedea în partea de sus a multor pagini din MDN, cum ar fi aceasta pentru proprietatea grid-area .

Aceste exemple le permit vizitatorilor MDN să încerce diferite valori pentru proprietățile CSS sau să încerce o funcție JavaScript, chiar acolo pe MDN, fără a fi nevoie să se îndrepte într-un mediu de dezvoltare pentru a face acest lucru. Proiectul de adăugare a acestor exemple este în desfășurare de aproximativ un an, puteți citi despre proiect și progresul până în prezent în postarea Aducerea de exemple interactive la MDN.

Conținutul acestor exemple interactive este păstrat în depozitul GitHub de exemple interactive. De exemplu, dacă doriți să găsiți exemplul pentru grid-area, l-ați găsi în acel repo sub live-examples/css-examples/grid . Sub acel folder, veți găsi două fișiere pentru grid-area , un fișier HTML și un fișier 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.zona.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; }

Un exemplu interactiv este doar o mică demonstrație, care folosește niște clase standard și ID-uri pentru ca cadrul să poată prelua exemplul și să-l facă interactiv, unde valorile pot fi modificate de către un vizitator al paginii care dorește să vadă rapid cum se face. lucrări. Pentru a adăuga sau edita un exemplu interactiv, mai întâi bifurcați depozitul de exemple interactive, clonați-l pe computer și urmați instrucțiunile de pe pagina Contribuție pentru a instala pachetele necesare din npm și pentru a putea construi și testa exemple la nivel local.

Apoi creați o ramură și editați sau creați noul exemplu. Odată ce sunteți mulțumit de el, trimiteți o solicitare de tragere la repo-ul Exemple interactive pentru a solicita ca exemplul dvs. să fie revizuit. Pentru a menține exemplele consistente, recenziile sunt destul de neplăcute, dar ar trebui să sublinieze modificările pe care trebuie să le faceți într-un mod clar, astfel încât să vă puteți actualiza exemplul și să îl aprobe, să comande și să îl adauge la o pagină MDN.

Cu aproape toate CSS acoperite acum (pe lângă exemplele JavaScript), MDN caută acum ajutor pentru a construi exemplele HTML. Există instrucțiuni despre cum să începeți într-o postare pe Forumul de discurs MDN. Consultați acea postare, deoarece oferă linkuri către un document Google pe care îl puteți utiliza pentru a indica că lucrați la un anumit exemplu, precum și alte informații utile.

Exemplele interactive sunt incredibil de utile pentru oamenii care explorează platforma web, așa că adăugarea la proiect este o modalitate excelentă de a contribui. Contribuția la exemplele CSS sau HTML necesită cunoștințe de CSS și HTML, plus capacitatea de a crea o demonstrație clară. Acest ultim punct este adesea partea cea mai grea, am creat o mulțime de exemple interactive CSS și am petrecut mai mult timp gândindu-mă la cel mai bun exemplu pentru fiecare proprietate decât scriu de fapt codul.

Date de comparație ale browserului

Destul de recent, datele de compatibilitate a browserului listate pe paginile MDN au început să fie actualizate prin Proiectul de compatibilitate cu browser. Acest proiect dezvoltă date de compatibilitate browser în format JSON, care pot afișa tabelele de compatibilitate pe MDN, dar pot fi și date utile în alte scopuri.

Datele de compatibilitate a browserului se află pe GitHub, iar dacă găsiți o pagină care are informații incorecte sau încă folosește tabelele vechi, puteți trimite o cerere de extragere. Depozitul conține informații despre contribuții, cu toate acestea, cel mai simplu mod de a începe este editarea unui exemplu existent. Am actualizat recent informațiile pentru proprietatea CSS shape-outside . Proprietatea avea deja unele date în noul format, dar era incompletă și incorectă.

Pentru a edita aceste date, am bifurcat mai întâi datele de comparație ale browserului, astfel încât să am propria mea furcă. Apoi l-am clonat pe mașina mea și am creat o nouă ramură în care să-mi fac modificările.

Odată ce am avut noua mea ramură, am găsit fișierul JSON pentru shape-outside și am putut să-mi fac editările. Aveam deja o idee bună despre suportul pentru browser pentru proprietate; Am folosit, de asemenea, exemplul live de pe pagina MDN din exterior pentru a testa pentru a vedea asistență atunci când nu eram sigur. Prin urmare, efectuarea modificărilor a fost un caz de lucru prin fișier, verificarea numerelor de versiune listate pentru suportul proprietății și actualizarea celor care erau incorecte.

Deoarece fișierul este în format JSON, este destul de simplu de editat în orice editor de text. Fișierul .editorconfig explică regulile simple de formatare pentru aceste documente. Există, de asemenea, câteva sfaturi utile în această listă de verificare.

Odată ce ați făcut modificările, puteți să vă comiteți modificările, să vă împingeți ramura la bifurcație și apoi să faceți o solicitare de tragere în depozitul de date Compat din browser. Este probabil ca, la fel ca și în cazul exemplelor live, recenzentul va avea câteva modificări de făcut. În PR-ul meu pentru datele Shapes, am avut câteva erori în modul în care am semnalat datele și a trebuit să fac unele modificări la linkuri. Acestea au fost simplu de făcut, iar apoi PR-ul meu a fost fuzionat.

Incepe

Puteți începe pur și simplu alegând ceva la care să adăugați și începând să lucrați la el în multe cazuri. Dacă aveți întrebări sau aveți nevoie de ajutor cu oricare dintre acestea, atunci forumul MDN Discourse este un loc bun pentru a posta. MDN este locul în care merg să caut informații, locul în care trimit dezvoltatori noi și dezvoltatori experimentați deopotrivă, iar puterea sa este faptul că putem lucra cu toții pentru a le îmbunătăți.

Dacă nu ați mai făcut niciodată un Pull Request pentru un proiect, este un loc foarte prietenos pentru a face primul PR și, după cum sper că am arătat, există modalități de a contribui care nu necesită scrierea niciunui cod. O abilitate foarte valoroasă pentru orice proiect de documentare este aceea de a scrie, edita și traduce, deoarece aceste abilități pot ajuta la ca documentația tehnică să fie mai ușor de citit și accesibilă pentru mai mulți oameni din întreaga lume.