Scrierea unei descrieri de provocare

Descrierile provocărilor sunt create de utilizatori, mai exact de persoanele care creează provocările. Aceste descrieri sunt extrem de importante deoarece nu doar definesc cu exactitate provocarea și cerințele acesteia, ci reprezintă și prima interacțiune a utilizatorilor cu provocarea. Din acest motiv, descrierile trebuie să fie clare și la obiect, pentru a oferi toate informațiile într-un mod simplu, pe care oricine îl poate înțelege.

Aspecte generale

• Limba engleză este limba oficială! Descrierile trebuie scrise în limba engleză. Comunitatea DojoCode este una internațională, așa că dacă nu vorbești limba engleză, poți cere ajutor pentru corectare și verificare ortografică.
• Fiecare opinie contează! Dacă există reclamații sau observații cu privire la descrierea provocărilor, acestea trebuie luate în considerare. Trebuie să avem în vedere faptul că, după ce ai lucrat mult la o provocare, cerința și soluția îți pot părea mult mai familiare decât unui utilizator care o vede pentru prima dată. Din acest motiv, este bine să inviți alți utilizatori să arunce o privire peste descriere, pentru a vedea dacă o înțeleg și dacă ceea ce au de făcut este clar și la obiect.
• Păstrează totul simplu! Provocarea ta poate fi tradusă în alte limbaje de programare. Din acest motiv, este bine ca descrierile să fie scrise cât mai independent de limbaj (language-agnostic) și să fie folosiți doar termeni abstracți, nu specifici unui anumit limbaj de programare. Dacă descrierea nu poate fi păstrată complet independentă de limbaj, elementele specifice unui limbaj ar trebui structurate într-un mod care să ajute la rezolvarea conflictelor de îmbinare (merge conflicts), mai exact: în fraze sau blocuri mai mari. Ar trebui evitată utilizarea mai multor concepte de limbaj într-o singură propoziție.
• Curat și clar! Descrierea și cerințele trebuie să fie clare și ușor de înțeles. Pentru fiecare utilizator, acesta este primul pas în alegerea provocării tale și înțelegerea ei.

Structură

Structura ar trebui să fie simplă, iar fiecare parte ar trebui să aibă un sens.

De exemplu:

• Descrierea trebuie să conțină o propoziție despre definiția provocării respective, urmată de cerințele pentru provocare.
• Adăugarea unei imagini care să reprezinte o previzualizare a soluției problemei.
• Un snippet cu datele de ieșire (output) și/sau datele de intrare (input) ale problemei.
• Dacă dorești, poți adăuga note suplimentare, detalii tehnice sau pași următori (follow-ups) între previzualizare și snippet-ul cu output-ul. Dar ai grijă să nu adaugi detalii inutile.
• Videoclipurile sau gif-urile sunt o idee bună dacă vrei să îți personalizezi mai mult provocarea. Îți recomandăm să folosești cât mai mult conținut original, așa că poți adăuga elemente precum videoclipuri sau gif-uri

Descrierea trebuie să fie scurtă și precisă. Secretul este ca descrierea să fie scurtă și ușor de înțeles. Nu are sens să te pierzi în detalii inutile, deoarece riști ca mesajul să se piardă. Încearcă să răspunzi la 3 întrebări simple: Ce, De ce și Cum?

SFAT

Este bine să începi cu lucrurile importante, folosește ideea piramidei inversate. Începe cu cele mai importante aspecte și lasă progresiv detaliile care nu sunt necesare pentru final.

Cerințe

Descrierea ar trebui să acopere toate cerințele pe care creatorul le așteaptă de la utilizator. Poți adăuga, de asemenea, câteva greșeli comune pe care crezi că un utilizator le-ar putea face. Astfel, dacă utilizatorul nu trece testele de verificare, poate consulta descrierea pentru a vedea dacă găsește ajutor.

• Ajută, dar nu dezvălui totul! Snippet-urile cu date de intrare (input) sau de ieșire (output) sunt foarte utile. Cu toate acestea, este recomandat să lași și utilizatorul să gândească, așa că asigură-te că nu dezvălui prea mult.
• Nu renunțăm! Încearcă să eviți expresii precum "deblochează soluția în caz că nu te descurci". Odată ce un utilizator deblochează o soluție, pierde puncte și pică provocarea.
• Cuvintele sunt secretul! Este foarte important să folosești imagini, acestea atrag atenția și ajută utilizatorul. Cu toate acestea, nu folosi imagini pentru orice; este mai bine ca descrierea și cerințele să rămână scrise în cuvinte. Poți folosi imaginile pentru a arăta utilizatorului o previzualizare a provocării.
• Atrage atenția asupra dificultății! Aceasta prezintă situația de la bun început. Astfel, este bine să evidențiezi complexitatea și dificultatea provocării.

Formatare

Poți folosi funcționalitatea markdown pentru a te ajuta să scrii o descriere mai organizată. Poți adăuga titluri, subtitluri, liste, tabele și multe altele. Totuși, nu abuza de ea; prea multe stiluri pentru un text relativ mic îl pot încărca prea mult.

• Folosește titlurile corecte! Nu folosi #Title pentru a introduce propoziții; în schimb, poți folosi titluri de tip ## Second level sau ### Third level.
• Imagini de calitate! Pentru imagini, poți folosi anumite programe speciale, astfel încât calitatea să fie bună și imaginea să fie clară.
• Simplu și frumos! Evită descrierile în care menționezi multe limbaje de programare. Folosirea mai multor limbaje de programare într-un singur paragraf poate fi prea încărcată și poate pierde atenția utilizatorului.

Ghiduri suplimentare

• Poți adăuga linkuri externe sau referințe dacă consideri necesar. Acest lucru nu este obligatoriu, dar în unele cazuri poate ajuta utilizatorul.
• Descrierile trebuie să conțină toate sursele de informare. Dacă ai folosit o altă provocare ca sursă de inspirație sau conținut de pe un alt site web, trebuie să menționezi acest lucru în descriere.

Resurse conexe

Pentru creatorii de provocări:

• 📖 Ghid de creare a provocărilor
• 📝 Orientări pentru redactarea provocărilor
• ✅ Orientări generale de codare

Pentru înțelegerea procesului de recenzie:

• 🔍 Cum sunt recenzate provocările
• 📋 Orientări de curatare