Aceasta este partea a treia a unei serii de cinci părți de postări conexe cu privire la validarea pachetelor R. Alte postări din serie sunt:
În această postare, vom arunca o privire mai atentă asupra documentației pachetului și a modului în care ajută la evaluarea „riscului” a unui pachet, scorul de documentare evaluează cât de complet și util este documentația unui pachet. Documentația pachetului vine în multe aspecte. Ar putea fi un exemplu de funcții, viniete sau chiar un site web. În timp ce nu credem fiecare pachet necesitate Aveți un site web, viniete și exemple. Dar absența tuturor celor trei indică de obicei documentația slabă.
La validarea pachetelor R, documentația contribuie cu aproximativ 15% la total.
Scorul 1: Documentarea obiectelor exportate
Scorul 2: Proporția paginilor de ajutor cu exemple
Un scor bazat pe proporția de paginile de ajutor care au exemple.
Scorul 3: fișier de știri
Un fișier de știri este un indiciu al unui ciclu de dezvoltare și eliberare. Îi ajută pe utilizatori să înțeleagă ce s -a schimbat între versiuni. Acest lucru detectează prezența unui dosar de știri. Desigur, pachetele R fac acest lucru interesant cu NEWS, NEWS.md, inst/NEWS.md și/sau Changelogs!
Scorul 4: Vignete
Aproximativ 40% din pachetele CRAN au o singură vinie, doar 10% având mai mult de o vinie – am verificat! Pentru simplitate, acest scor este o valoare binară simplă, bazată pe dacă un pachet are viniete.
Scorul 5: site -ul pachetului
Scorul 6: Știri actualizate la versiunea curentă
Fișierul de știri al pachetului este învechit sau lipsit, ceea ce face dificilă urmărirea modificărilor recente, a remedierii erorilor sau a actualizărilor. Această lipsă de transparență poate prezenta riscuri, deoarece utilizatorii nu sunt în măsură să verifice dacă au fost implementate actualizări critice.
Rezumat
Cu toții putem fi de acord că un pachet nu are nevoie de toate componentele descrise mai sus. Este perfect rezonabil să ai puține exemple, dar viniete foarte detaliate. Punctul important este de a investiga pachetele care au o mică documentație.
Exemple
Folosind pachetele din postarea anterioară a blogului și omiterea scorurilor în care toate pachetele au obținut 1, avem următoarele rezultate
| Pachet | Știri actuale | VIGNETTE | Exemple |
|---|---|---|---|
| DRAT | 1.00 | 1.00 | 0,43 |
| microbenchmark | 0,00 | 0,00 | 0,20 |
| Shinyjjs | 1.00 | 1.00 | 0,90 |
| tibble | 1.00 | 1.00 | 0,61 |
| tsibble | 0,00 | 1.00 | 0,82 |
Toate pachetele folosesc controlul sursei, au un site de pachet și oferă documentație. {microbenchmark} Nu are știri/Changelog. În mod similar, lipsesc viniete. Dar amintiți -vă că are încă un scor general de pachet. Ideea din spatele lui Litmus, nu este că un pachet trebuie să fie perfect, ci să adopte o abordare pragmatică a notării.
Ciudat, The {tsibble} Pachetul are un fișier de știri, dar nu menționează cea mai recentă versiune, dar cred că aceasta a fost o supraveghere.
Pentru actualizări și revizii la acest articol, consultați postarea originală
