Ho preso in considerazione la possibilità di creare moduli e simili per varie lingue e altre cose open source. Dove la documentazione non è specificata, ma piuttosto è di fatto comune o completamente ad hoc; dovrei provare a migliorare da quello standard nel mio codice se non è in linea con quello che ho imparato ad essere una buona documentazione da fonti attendibili ( Code Complete et al)?
O dovrei mantenere la coerenza su tutti, indipendentemente dalla qualità?
La coerenza in un progetto è cruciale sia per il codice sorgente stesso che per la documentazione. Le persone che lavorano al progetto sono abituate a utilizzare gli standard che hanno usato per anni e andrebbero persi di fronte a un pezzo di codice o una parte di una documentazione che, secondo te, è meglio, ma non ha nulla a che fare con il codebase o la documentazione rimanenti.
Inoltre, tieni presente che non è perché tu pensi che qualcosa sia cattivo, significa che lo è. Fare riferimento al codice completo non cambia nulla. Ciò che potresti criticare potrebbe avere la sua origine in alcuni elementi relativi al progetto, e mentre il codice completo dice che è sbagliato, chiunque abbia lavorato al progetto per anni sarebbe d'accordo sul fatto che in questo caso specifico, è l'unica scelta.
Se vuoi migliorare la documentazione di un progetto open source esistente, raccogli un feedback da altre persone che partecipano a questo progetto, e se vedi che tutti sono d'accordo sul fatto che la documentazione effettiva è troppo male, allora, potresti volere per riscriverlo da zero, seguendo le migliori pratiche e mantenendo la coerenza allo stesso tempo.
Il mantenimento della coerenza è probabilmente meglio da fare inizialmente, ma vorrei contattare i proprietari del progetto e chiedere se è possibile suggerire miglioramenti alla loro documentazione. Se sono d'accordo, giustifica i tuoi suggerimenti e fornisci esempi.
"Bad" è negli occhi di chi guarda. I tuoi "cattivi" potrebbero essere i loro "belli". Fino a quando ea meno di non diventare un contributore significativo, dovresti seguire lo stile stabilito.
Leggi altre domande sui tag open-source documentation