Mantiene la versione della documentazione uguale alla versione del progetto

Naviga le tue risposte
7

Oltre a questa domanda Git deve essere utilizzato per la documentazione e la gestione dei progetti? Il codice dovrebbe essere in un repository separato? Voglio chiedere se è consigliabile mantenere la versione della documentazione (ad esempio: per un'API REST) uguale a versione progetto , assumendo che il codice e la documentazione si trovino nello stesso repository git.

Quindi questo significa che se le modifiche vengono inviate nel codice del progetto e la versione del progetto aumenterà, la versione della documentazione aumenterà anche se non ci sono cambiamenti nella documentazione.

Quali sarebbero i vantaggi e gli svantaggi di questa pratica?

Lo sto chiedendo perché voglio la documentazione (nel mio caso la documentazione è generata usando apidocjs dai commenti di codice di un progetto node.js ) per copiare automaticamente la versione dalle impostazioni del progetto ( package.json ). Ciò semplifica la gestione delle versioni della documentazione, perché non devo ricordarmi di aggiornarlo, quindi sarà sempre sincronizzato con il codice.

So che questa domanda è soggettiva, ma non ho trovato nessun chiarimento su questo.

    
posta Alexandru Irimiea 27.03.2017 - 23:15
fonte

2 risposte

4

To keep the documentation version the same as project version

non è versioning della documentazione . Si afferma semplicemente "la documentazione è stata estratta con quella versione del software".

Ovviamente ha un vantaggio che l'utente può sempre facilmente verificare che la versione del documento corrisponda alla versione del software e ottenerne una aggiornata quando non lo fa.

Il grosso svantaggio di farlo con la tua documentazione (o API) è che non fornisci agli utenti informazioni se è diverso dal precedente. Quando si incrementa la versione del software, lo si fa esattamente per indicare una modifica. Gli utenti scopriranno presto che la versione di un documento incrementato non significa contenuto aggiornato e sarebbe resiliente per verificare la presenza di nuove versioni.

Nella documentazione della vita reale (e, ancora, API) non cambia con ogni piccola versione del software, specialmente se ne hai diversi tipi e livelli. Distingue i diversi attributi del documento

  • la sua versione
  • versioni del software a cui si applica (spesso solo 'dalla' versione)
  • versione del software con cui è stata raggruppata
risposta data 06.04.2017 - 09:11
fonte
1

Se la documentazione viene generata automaticamente dal codice, non è necessario memorizzarla sotto il controllo della versione - nello stesso modo in cui non è necessario memorizzare il codice compilato in VC. Hai solo bisogno di memorizzare qualsiasi script o file di impostazioni dello strumento necessari per generare la documentazione dal codice. L'utente può rigenerare la documentazione al volo, forse come parte del processo di compilazione.

    
risposta data 06.04.2017 - 10:11
fonte

Leggi altre domande sui tag

Usare le code per disaccoppiare le funzioni / evitare le chiamate dirette? "Il metodo di fabbrica è una specializzazione del metodo dei modelli". Come?