Recent, Habr a început să apară destul de multe articole despre diverse aspecte ale programării, care sunt poziționate ca articole pentru "începători". Între timp, este pentru începători că aceste articole sunt adesea incomprehensibile: uneori sunt prea complicate, uneori nu răspund la întrebările pe care trebuie să le facă, uneori sunt greu de percepție.
Identificați publicul țintă
Cred că este evident că articolele care se concentrează pe persoane cu niveluri diferite vor arăta complet diferite. Cu toate acestea, majoritatea articolelor marcate "pentru începători" sunt destinate persoanelor care sunt familiarizate superficial cu programarea.
Determinați cunoștințele inițiale necesare pentru a vă înțelege articolul
Sunt de acord, nu este atât de dificil să scrieți la început ceva de genul:
"Pentru a înțelege acest articol, cititorul ar trebui să aibă cunoștințe inițiale despre C:
- să fie capabil să compileze și să execute aplicația
- Cunoașteți sintaxa, tipurile de date de bază și structurile de management »
Nu durează prea mult, dar ajută mulți cititori. Crede-mă, dacă începi articolul astfel:
Compilați următorul cod:
atunci cititorii nu înțeleg ce li se cere. Nu uitați, odată ce nu ați știut cum să utilizați compilatorul.
Faceți un articol cât mai bun posibil
Designul bun și competent este unul dintre cheile unei înțelegeri ușoare a materialului.
Încercați să scrieți întregul cod ca întreg
Am văzut articole și cărți în care codul a fost citat în bucăți separate. Acest lucru duce la dificultatea cititorului de a înțelege codul, fără a menționa faptul că nu poate să copieze și să execute acest cod. Desigur, puteți scrie, de exemplu, funcții diferite în listări diferite. Acest lucru este chiar bun, deoarece facilitează înțelegerea. Dar nu rupeți o bucată de cod logic omogenă.
Un exemplu de program care scoate "Hello, World":
Un exemplu de program care scoate "Hello, World":
la care se referă.
Dacă trebuie să spargeți codul în mai multe liste, ar fi frumos la sfârșitul articolului să reintroducăți tot codul într-o singură listă sau chiar să dați un link pe care acest cod poate fi descărcat.
Verificați întotdeauna codul înainte de al introduce în articol
Cititorul vrea cel mai puțin să stea și să încerce să înțeleagă de ce exemplul din articol nu funcționează.
Din același motiv, dacă codul dvs. depinde într-un fel de mediu sau de compilator, specificați-l separat.
În linia 1 conectăm fișierul antet. care conține clasele, funcțiile și variabilele necesare pentru a lucra cu fluxul I / O al C ++. Conectăm acest fișier pentru a folosi obiectul cout, care este fluxul de ieșire standard.
În linia 4 începe funcția principală - din acest punct începe activitatea programului nostru.
În cele din urmă, în linia 6, scoatem expresia "Bună ziua, lume" la fluxul standard de ieșire cout. Pentru aceasta, se utilizează o sintaxă destul de simplă, folosind operatorul <<. Слева от оператора записывается объект потока (в нашем случае cout), справа — выражение, которое должно быть выведено в этот поток.
Puneți-vă în locul cititorului
Imaginați-vă ce locuri în exemplele dvs. nu pot fi foarte clare și explicați-le în detaliu. Dacă sunteți prea leneș pentru a descrie câteva lucruri ușor de găsit pe Internet sau cărți, dați doar o legătură cu resursa, unde puteți citi despre ele.
Încearcă să nu complici codul și să eviți perfectionismul
Nu uitați, scrieți un articol pentru un începător. Dacă puteți face codul mai ușor, este mai bine să faceți acest lucru. Dacă doriți să arătați că codul poate fi îmbunătățit (chiar dacă este complicat), scrieți despre el după o soluție simplă. Imaginați-vă că explicați persoanei modul în care funcționează declarația de returnare și de exemplu a decis să scrie o funcție care compară două numere și returnează cea mai mare (sau orice, dacă cifrele sunt egale). Nu scrie ceva de genul
Scrieți un cod simplu și ușor de înțeles:
Să se îmbunătățească de zece ori - nu contează dacă sarcina dvs. este să arătați esența metodei și nu implementarea concretă a acesteia.
Încercați să rămâneți la un nivel în tot articolul
Dacă începeți să scrieți un articol la un nivel de bază și să spuneți în detaliu lucruri simple, faceți acest lucru până la sfârșitul articolului. Dacă în mijlocul articolului încetați brusc să explicați câteva lucruri, atunci cititorul poate pierde complet firul articolului și se confuză.
Stick la un stil în tot articolul
Nu contează dacă scrieți în stilul "academic" sau în stilul "acum, tipule, ne vom compila creația". Este important să fiți consecvenți și să nu treceți de la o narațiune oficială la una informală și înapoi de zece ori pe articol.
Încercați să vă structurați gândurile
Încercați să ajutați cititorul
concluzie
Trimiteți-le prietenilor: