[🆕]: Documentazione

[Cadienvan]

Questa issue viene aperta per poter esprimere il proprio interesse verso l'argomento nel titolo.

Chiunque sia interessato a questo argomento può mettere un 👍 su questa issue.

Chiunque tra gli Ambassador sia interessato ad assegnarsi l'argomento per una prima versione può indicarlo in un commento o, più semplicemente, assegnare a se stesso la issue tramite l'interfaccia di GitHub.

Chiunque sia interessato a contribuire può aggiungere un commento a questa issue.

Chiunque sia interessato a proporre un argomento alternativo può farlo nella apposita discussione.

N.B. Non necessariamente l'argomento sarà trattato in un capitolo a sé stante. Potrebbe essere trattato in un capitolo più ampio o in un capitolo dedicato ad un argomento correlato. Questa issue viene aperta esclusivamente per valutare l'interesse nell'argomento.

[Tonel]

@federico-trotta Credo che sia la persona giusta da sentire per questo capitolo

[Cadienvan]

Sarebbe un piacere avere qualcuno con competenze a riguardo che possa supportarci nella stesure :)

[federico-trotta]

Grazie @Tonel ! @Cadienvan contribuisco volentieri! :)

[Cadienvan]

@elgorditosalsero che ne pensi di de-assegnarti e ri-assegnarti la issue così si apre il branch e cominci a creare il file md, così che si possa cominciare ad aprire una conversazione a riguardo?

[create-issue-branch[bot]]

Branch add/documentazione created!

[elgorditosalsero]

@Cadienvan fatto 😄

Domani vedo di prendermi del tempo per iniziare a stendere due righe in quanto c'è molto da dire

@federico-trotta sentiti libero di aggiungere cose e confrontiamoci in modo da non scrivere le stesse cose e "pestarci i piedi" tra di noi 😂

[Cadienvan]

Ciao @elgorditosalsero avevi già in mente una table of contents per questo capitolo? Così magari possiamo cominciare a coinvolgere @federico-trotta !

[federico-trotta]

Ciao @Cadienvan , @elgorditosalsero .

A grandi linee, per adesso le mie idee sono queste:

• Necessità ed importanza della documentazione
• Linee guida per una corretta documentazione software
  • Prerequisiti
  • Requisiti
  • Installazione
  • Rimandi a terze parti
  • Esempio semplice di utilizzo
• Standardizzazione dei commit
• Collaborazione coi Technical Writers (questo sarebbe da sbarco sulla luna XD)

A disposizione per collaborare. :)

[elgorditosalsero]

Hola!

@federico-trotta nel secondo punto parliamo di documentazione di "prodotto"?

Nel senso documentazione di come dovrebbe funzionare una feature prima di iniziare gli sviluppi?

Per poi sfociare in documentazione pubblica?

Vogliamo anche parlare di documentazione tecnica?

Magari possiamo confrontarci!

[federico-trotta]

Hey @elgorditosalsero . Good point!

Allora, nel secondo punto pensavo alla documentazione di prodotto "sì e no". Ovvero: quelle potrebbero essere delle indicazioni da tenere presente quando si pubblica un prodotto (perché, in effetti, in qualche modo lo è :) ) sul proprio GitHub (anche magari per progetti open source condivisi eh). Il che giustificherebbe, secondo me, un "esempio di semplice utilizzo".

Se, invece, si parla di lavorare in una azienda di prodotto o software house o simili, quelle linee guida del secondo punto, secondo la mia esperienza, possono andare bene ma eviterei l'esempio di utilizzo (o, comunque, lo renderei ancora più "semplice").

Non so fino a che livello di profondità vogliate arrivare, ma mi viene in mente che:

• "documentazione di come dovrebbe funzionare una feature prima di iniziare gli sviluppi". Questo secondo me può essere ottimo da prendere in considerazione in quanto si tratta di creare una specifica tecnica. Potrebbe essere interessante dare delle linee guida standard sul come progettare "su carta" una feature di un prodotto (dove si indica cosa deve fare la feature, quando la si considera conclusa ed implementata nel software, ecc...).
• "Per poi sfociare in documentazione pubblica?". Questo secondo me potrebbe rientrare in "Collaborazione coi Technical Writers". Io sono fermamente convinto che, da un certo punto in poi, la doc deve passare di mano dai dev ai tech writers, e mi piacerebbe discuterne :)
• "Vogliamo anche parlare di documentazione tecnica?". Per me, assolutamente sì. :)

Sì, confrontiamoci. Ti va di sentirci su LinkedIn per fissare un meeting? :)

[elgorditosalsero]

@federico-trotta mea culpa per le tempistiche, ma mi so concentrato sul lavoro dato che siamo in periodo reward cycle!

Ti scrivo su In così ci aggiorniamo 😄

[elgorditosalsero]

Durante il 1:1 con @federico-trotta, ci siamo confrontati e abbiamo deciso di procedere in questa maniera:

• Pagina principale chiamata Documentazione con intro relativa a Necessità ed importanza della documentazione
• Sottopagine così divise:
  • Specifiche di prodotto, che includerà Prerequisiti, Requisiti ed Installazione
    • Interna
    • Pubblica
  • Specifiche tecniche, che includerà come suddividere la feature tecnica in base al contenuto delle specifiche di prodotto
  • Specifiche di testing, che includerà come scrivere un piano di test basato sulle specifiche appena menzionate
  • Standardizzazione dei commit
  • NICE TO HAVE: Collaborazione coi tech writer

[Cadienvan]

Mi sembra una bomba, non vedo l'ora!!