Importanza di diffing e merging per la documentazione delle specifiche di progettazione

Per la discussione nel tuo caso, è importante tenere in considerazione che la funzionalità di diffusione è già disponibile nella tua "configurazione" (più su quella di seguito).

Considera la discussione sulla messa a fuoco delle differenze tra quanto è facile hai bisogno che sia, o più precisamente, hai bisogno di caratteristiche di usabilità "extra" fornite da strumenti diff mirati a lavorare con il codice (maggiori informazioni su quello sotto).

La capacità di diff è dovuta al fatto che tutti i documenti sono considerati in grado di essere esportati in PDF. Il fatto è che ci sono strumenti ^{1 , 2} in grado di produrre diffs PDF.

• ^{Per completezza, vale la pena notare che anche il PDF può essere salvato come testo normale , che in teoria renderebbe le cose essenzialmente le stesse che funzionano con le diffsche di codice di routine, ma poiché tutti i miei tentativi di usarlo mi hanno portato a spazzatura senza senso, non andrò oltre.}

Nella mia esperienza, lavorare con le diffs PDF era praticamente vicino alle normali diffs del codice, nel senso che si possono riferire, descrivere e discutere di questi in modo significativo. "In 7th diff a pagina 654, la parola foo deve essere sostituita con bar " . La revisione di alcune differenze di 200-300 in 2-3 file nel giro di 2-3 ore è stata perfettamente fattibile in questo modo.

• Aggiungendo che il PDF supporta anche ³ annotazioni , la revisione delle differenze PDF può sembrare quasi come lavorare con un vero strumento di revisione del codice come Cricible o Collaboratore di codice .

La domanda che dovresti porre qui è, ancora, quanto è facile hai bisogno che sia? L'utilizzo anticipato della diff doc comporta scenari in cui gli strumenti di revisione del codice offrono notevoli vantaggi rispetto alle diff / PDF?

Diciamo che avere una revisione di "round" di 1000 diff in 100 file in un giorno è perfettamente ragionevole con uno strumento di revisione del codice decente, ma non riesco nemmeno a immaginarlo con le diffs PDF, perché è improbabile una richiesta in uno strumento in grado di farlo, dato l'uso tipico di PDF.

Per il tuo caso specifico, direi che non ha importanza per i seguenti motivi:

• È già un documento a controllo di versione, quindi puoi tornare indietro nel tempo per rivedere le vecchie versioni se necessario.

• È già strettamente controllato per le copie scrivibili.

• Il dolore che ti porta a considerare una forma più facilmente unita sembra essere un evento a bassa frequenza, come evidenziato dalle risposte contrastanti dei tuoi compagni di squadra. Se avessero tutti sperimentato quel problema su base regolare, avrebbero supportato un formato più facilmente unito.

Come soluzione alternativa, prendi in considerazione la possibilità di generare un documento redline aggiuntivo che evidenzi le modifiche tra le versioni. Nonostante le molte frustrazioni, MS Word offre funzionalità di tracciamento delle modifiche e può tenere traccia delle modifiche da più utenti all'interno di un documento. Per mantenere pulito il ramo del documento di linea principale, è possibile creare un ramo separato per i documenti redline.

Ecco alcune controindicazioni che potrebbero farmi cambiare la mia risposta a "sì, conta incredibilmente!"

• Se il documento potrebbe essere modificato al di fuori del core team e reimmesso nel flusso del flusso di lavoro, vorrei insistere per un facile unione e amp; confrontare le capacità. Ad esempio, se si scambiavano documenti di progettazione con un cliente e i requisiti erano in alto flusso, l'unione sarebbe fondamentale.

• Se esistono più versioni del documento e sono modificate allo stesso tempo. Lo scenario classico qui è inviare via email una bozza specifica che è modificata da più destinatari. Gli editori quindi inviano le e-mail alle loro modifiche solo al proprio gruppo di revisori che poi ripetono il ciclo. (E sono stato lì, fatto su questo. Il controllo dei documenti qui fa male!)

• Se non avevi un repository centrale per fornire una nota, buona, ultima copia del documento.

• Se c'era molta sovrapposizione di contenuti nei vari documenti e il contenuto che si sovrapponeva era soggetto a frequenti cambiamenti, quindi sono stati necessari più aggiornamenti del documento per una singola modifica del codice.

Per rispondere correttamente alla tua domanda, dobbiamo prima valutare se facilmente potrebbe mai essere usato per descrivere il processo di confronto e fusione dei documenti.

Documents are not code. There are many obvious differences between merging code and merging documents, but some subtle ones also: if a mistake is made when merging code there are many automated ways of detecting this, ranging from compiler errors to formal unit-testing. Conversely, with documents, a visual inspection will almost always be required; just because document parts don’t appear to conflict, (and still conform to DITA rules in this scenario) there is no guarantee that a change in a title (or even the way it is rendered) in one part of the document can leave another part redundant or invalid.

Quanto sopra è un estratto di un recente post sul blog da me stesso:

Revisione di documenti XML per una N -Way Unisci

La fusione N-Way è stata considerata perché i documenti hanno un contenuto narrativo. In quanto tali, vengono spesso modificati e rivisti in un modo più ad hoc di codice che ha una struttura molto rigida (per quanto riguarda un compilatore o un interprete).

La mia opinione dopo aver lavorato su una soluzione per questo problema è che questo tipo di unione è improbabile che sia mai "facile" ma è certamente possibile renderlo gestibile.

Per illustrare alcune delle sfide, ecco una vista di un'app web prototipo (quella utilizzata per il blog) per esplorare i metodi di revisione per un'unione di documenti N-Way: