# Scrivere un README efficace > [! nota]- > Il contenuto di questa pagina è generato dalla trascrizione audio/video e dalla trasformazione del testo dal contenuto e dai link di questa fonte. Fonte: [https://fosdem.org/2025/schedule/event/fosdem-2025-4990-how-to-write-a-killer-readme/](https://fosdem.org/2025/schedule/event/fosdem-2025-4990-how-to-write-a-killer-readme/) <video src=“https://video.fosdem.org/2025/h2215/fosdem-2025-4990-how-to-write-a-killer-readme.av1.webm” controls></video> ## Riepilogo e punti salienti: La sessione 'How to Write a Killer README' tenuta da Emily Omier durante FOSDEM 2025 si concentra sull'importanza di un README efficace per i progetti open-source. Un README ben fatto non solo guida gli utenti su come iniziare con il software, ma serve anche come strumento di promozione e differenziazione rispetto ad altri progetti. Emily Omier fornisce consigli pratici su come migliorare i README, rendendoli strumenti potenti per attrarre e mantenere utenti e contributori. **Importanza del README** Un README è spesso la prima impressione che un utente ha di un progetto open-source. È essenziale per spiegare chiaramente cosa fa il progetto, quali problemi risolve e come differisce dalle alternative. Un README efficace aiuta gli utenti a decidere rapidamente se il progetto è adatto a loro, risparmiando tempo e risorse. **Elementi chiave di un README** Emily sottolinea che un README dovrebbe includere una chiara descrizione del progetto, il suo valore unico, e casi d'uso concreti. È importante anche indicare quando il progetto potrebbe non essere adatto a qualcuno, mostrando rispetto per il tempo degli utenti. Inoltre, il README può fungere da collegamento tra il progetto e l'azienda che lo supporta, se applicabile. **Esempi pratici e social proof** La presentazione include esempi di README efficaci, come quello del progetto Argilla, che combinano prove sociali e casi d'uso per dimostrare il valore del progetto. Emily enfatizza l'importanza di includere collegamenti a linee guida per i contributori nel README, facilitando così il coinvolgimento della comunità. **Conclusione e suggerimenti** Per chiudere, Emily Omier invita i partecipanti a rivedere i loro README esistenti, integrando i suggerimenti forniti per renderli più efficaci e accattivanti. Un README ben strutturato può aumentare significativamente l'attrattiva di un progetto open-source, favorendo la crescita e la sostenibilità della comunità. ## Significato per una trasformazione eco-sociale Un README efficace è fondamentale per la sostenibilità e la crescita delle comunità open-source, promuovendo una partecipazione inclusiva e informata. Per i designer eco-sociali, è essenziale comunicare chiaramente il valore e l'impatto sociale del progetto, facilitando la collaborazione e l'adozione di pratiche sostenibili. Le sfide includono la necessità di bilanciare dettagli tecnici e accessibilità, oltre a garantire che il progetto sia rappresentato in modo equo e trasparente. Strumenti come GitHub e piattaforme di documentazione open-source possono essere utilizzati per migliorare la qualità dei README, mentre le questioni etiche riguardano la trasparenza e l'inclusività nel comunicare l'impatto del progetto. ## Slides: | | | | --- | --- | | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_001.jpg\|300]] | La prima diapositiva introduce il tema della presentazione: come scrivere un README efficace. Emily Omier è la relatrice e si concentra sull'importanza di un README ben strutturato per i progetti open-source. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_002.jpg\|300]] | Emily Omier si presenta come consulente di strategia di posizionamento e prodotto per aziende open-source. È anche conduttrice del podcast 'The Business of Open Source' e co-organizzatrice dell'Open Source Founders Summit. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_003.jpg\|300]] | Emily sottolinea che il README è più importante di quanto si pensi. È un documento cruciale che può influenzare la percezione e l'adozione di un progetto open-source. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_004.jpg\|300]] | La diapositiva elenca gli obiettivi di un README: guidare l'installazione, aiutare a valutare l'idoneità del progetto, scoraggiare usi inappropriati, ottenere stelle e mostrare casi d'uso. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_005.jpg\|300]] | Un README è paragonato a una homepage per un progetto, fornendo una panoramica essenziale e invitante che attira e guida i nuovi utenti. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_006.jpg\|300]] | | | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_007.jpg\|300]] | Un README dovrebbe definire chiaramente il progetto, comunicare il valore e le differenze rispetto ad altre opzioni, delineare i casi d'uso ideali ed esempi concreti, e infine guidare l'utente nell'iniziare. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_008.jpg\|300]] | Se un progetto è supportato da un'azienda, il README è il luogo dove stabilire una connessione tra il progetto e i prodotti o servizi dell'azienda, informando gli utenti della sua esistenza. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_009.jpg\|300]] | La diapositiva discute l'importanza di avere un logo e una chiara dichiarazione di posizionamento per il progetto Argilla, che è stato acquisito da Hugging Face. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_010.jpg\|300]] | Descrive il valore differenziato del progetto Argilla, fornendo una descrizione dettagliata ma concisa delle sue caratteristiche uniche. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_011.jpg\|300]] | La diapositiva offre una combinazione di prove sociali e casi d'uso, dimostrando come il progetto viene utilizzato nella pratica. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_012.jpg\|300]] | Continua a mostrare prove sociali e casi d'uso, ma manca una sezione su chi non dovrebbe usare Argilla, per risparmiare tempo agli utenti. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_013.jpg\|300]] | Finalmente si arriva alla sezione che guida l'utente a iniziare con il progetto, dopo aver fornito tutte le informazioni preliminari. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_014.jpg\|300]] | Per scrivere un README efficace, bisogna spiegare perché dedicare tempo al progetto, chiarire le situazioni in cui il progetto non è adatto e, se applicabile, collegarlo all'azienda. | ![[FOSDEM 2025/assets/How-to-Write-a-Killer-README/preview_015.jpg\|300]] | Ringraziamenti finali da parte di Emily Omier, con riferimenti al suo podcast e al suo sito web per ulteriori risorse e contatti. ## Link [Slides](https://fosdem.org/2025/events/attachments/fosdem-2025-4990-how-to-write-a-killer-readme/slides/238604/How_to_Wr_cHaajL4.pdf) [Video recording (AV1/WebM)](https://video.fosdem.org/2025/h2215/fosdem-2025-4990-how-to-write-a-killer-readme.av1.webm) [Video recording (MP4)](https://video.fosdem.org/2025/h2215/fosdem-2025-4990-how-to-write-a-killer-readme.av1.mp4) [Video recording subtitle file (VTT)](https://video.fosdem.org/2025/h2215/fosdem-2025-4990-how-to-write-a-killer-readme.vtt) [Chat room(web)](https://chat.fosdem.org/web) [Chat room(app)](https://chat.fosdem.org/app)