Problemi di documentazione multipli in un singolo bug

Sono uguali a conflitti di problemi nel codice. L'unica differenza è che uno di loro (i cambiamenti in un punto che hanno conseguenze non volute in un altro) sono leggermente meno simili a quelli che si verificano nel testo che nel codice.

La maggior parte degli sviluppatori visualizza il codice del computer come un'entità dinamica attiva il cui comportamento non è prontamente previsto e che non è possibile comprendere correttamente senza eseguirlo nel contesto di test e produzione, e giustamente. Ma molti sviluppatori ritengono anche che il testo sia una cosa statica, banale che puoi capire semplicemente guardandola, e che puoi quindi correggere banalmente senza avere una visione più ampia. Questo è un po ' vero, ma anche nel testo è necessario preservare la coerenza (ad esempio per un linguaggio ubiquitario come definito da DDD), mantenere i riferimenti intatti e diffidare di inosservate auto contraddizioni. Pertanto, anche la documentazione trae profitto dall'essere cambiata in un modo alla volta e con una comprensione dell'intero "codice base".

I cons appaiono quando le modifiche del documento sono versionate (e quando non lo sono, chiunque sia responsabile per la garanzia della qualità avrà tempo per verificare se i problemi sono stati risolti o meno) e quando una particolare versione del documento integra le correzioni solo per una parte dei problemi elencati nell'errore originale .

Casi come questo potrebbero diventare difficili da tracciare:

^{Issues listed in bug under 1 through 20 were resolved in version 25, but issues 15 and 17 reappeared again in version 27 and later, issues 40 through 50 were resolved in version 31, issues 70 through 80 were resolved in version 118 of the guide.}

Vale la pena notare che sopra non significa che si debba necessariamente aprire un bug dedicato per ogni singolo problema che scoprono. Non sei il solo a trovarlo "più conveniente per creare un singolo bug per più problemi nello stesso documento" - nella mia esperienza è stato tipicamente il caso nelle revisioni dei documenti: uno studia il doc, elenca il problemi e li mette in un singolo bug per ulteriore tracciamento.

La via d'uscita che ha dimostrato di funzionare bene per me è quella di permettere di dividere l'elenco originale estraendo una parte dei problemi in nuovi bug dedicati, in modo da renderli chiari ai lettori del bug originale in cui il " estratti "problemi sono andati.

Dì, se uno si aspetta che la prossima versione del documento risolva 10 di 100 problemi elencati nel bug originale, allora si può creare un nuovo bug che elenca solo questi 10 problemi e modificare il bug originale, informando i lettori che 10 problemi sono sarà indirizzato separatamente per ogni nuovo bug.

Un nuovo bug separa chiaramente i problemi da controllare e verificare in una determinata versione, mentre l'aggiornamento apportato al bug originale de-definisce questi problemi, lasciando i restanti 90 da affrontare.

Quando ci si aspetta che 90 di 100 problemi siano affrontati, l'approccio è essenzialmente lo stesso, uno "estrae" i rimanenti 10 problemi in un nuovo bug dedicato e procede con la gestione di 90 problemi rilevanti per la versione di doc, usando l'errore originale per tenere traccia dei progressi relativi a questi 90 problemi e per informare il lettore che altri problemi devono essere risolti per bug separato.

Il modo in cui la lista è divisa segue fondamentalmente il modo in cui i problemi vengono affrontati nelle conseguenti versioni dei documenti; parti della lista che dovrebbero essere gestite in una particolare versione sono "estratte" per semplificare il tracciamento di come sono state corrette.