book
book copied to clipboard
Il-Libro-Open-Source
Aggiunto file principale per documentazione
Aggiunto il file principale della documentazione che spiega la necessità e l'importanza della documentazione ed anticipa le tematiche di cui trattare successivamente nelle sotto sezioni (verranno aggiunte successivamente).
CIao @federico-trotta, a me piace molto, infatti di base ho approvato il contenuto. Credo però che manchi un punto iniziale nella discussione e un'aggiunta nel mezzo. Provo a spiegarmi.
Si parte subito col dire che la documentazione è un'attività secondaria, senza però indicare cosa sia. Partendo dal presupposto che chi legge questo contenuto dovrebbe saperlo, potrebbe non essere così, quindi spiegherei cos'è una documentazione tecnica e, magari, alcuni accorgimenti su come scriverla (Evitare i papiri, arrivare dritti al punto, spiegare bene il contesto attorno a quanto si sta leggendo, ecc.). Cosa ne pensi?
Inoltre, credo che nel mezzo starebbe molto bene un accenno ai tool, come markdown, che possono favorire la stesura di documentazione. Non andrei in quelli enterprise come Confluence in quanto, appunto, business-related, ma più su tool di facile accesso.
Ciao @Cadienvan hai sollevato ottimi punti!
Concordo di non trattare tool specifici. Parlerei del markdown in via principale; in via secondaria, accennerei al reSTructured text perché è mooooolto utile per documentare progetti Python (è utile in generale come il markdown, ma resterei a Python in quanto discussione più adatta per un pubblico di developers).
Penso di lavorarci in settimana. :)
Ciao @federico-trotta , ho visto che mentre alcune suggestion le hai portate dentro, altre sono ancora pendenti. Non le reputi corrette oppure è stata solo una dimenticanza? Giusto per sapere, così riapprovo una volta sola ahah
Ciao @Cadienvan , i suggerimenti non committati li ritengo non corretti. :)
PS: il contenuto, comunque, ancora non è concluso, eh. Mancano ancora i seguenti:
- La gestione delle specifiche tecniche.
- La gestione delle specifiche di testing.
- La standardizzazione.
- La collaborazione coi Technical Writers (che però è un desiderata).
Lato mio, penso sia più giusto che qualche dev si occupi della parte della gestione delle specifiche tecniche e di testing (magari anche il buon @elgorditosalsero :) ), ed io do qualche indirizzo/suggerimento.
Io lavorerò (spero in settimana!) sugli ultimi due, quindi standardizzazione e collaborazione coi tech writers (a cui seguiranno sicuramente suggerimenti da chi vorrà contribuire :) ).
Concordi? :)
@federico-trotta @elgorditosalsero piccolo amorevole ping che sapete sono "obbligato" a fare.. Come va con la stesura? Posso supportarvi in qualche modo?
Hey @Cadienvan . Super sorry: sono un po' indietro causa impegni lavorativi e familiari. Mi impegno a fare quanto prima sugli ultimi due topics (in attesa di dare supporto per gli altri due menzionati :) )
Ottimo @federico-trotta , il ritardo che noti in questo commento ti fa capire che ti capisco molto bene ahahah nessuna fretta, io pingo a promemoria.
@Cadienvan con gli ultimi commit, penso di aver messo tutto quello di cui avevano discusso ormai secoli fa... XD
Lascerei a te e @elgorditosalsero di rivedere bene le parti di gestione delle specifiche tecniche e di testing perché sicuramente avete più esperienza di me in questo. :)
Per il resto, mancasse qualcosa in generale, resto a disposizione.
Complimenti @federico-trotta sei arrivato a ben 7 approvazioni e stiamo in questo momento pubblicando il tuo capitolo!!!