Come generare materiale didattico dal tuo lavoro [chiuso]

Question

Come generare materiale didattico dal tuo lavoro [chiuso]

#1 da (3 voti)

2

Catalyst: recentemente il mio team è stato incaricato di portare a casa un grande progetto software su cui è stato lavorato per oltre 20 anni. Alcuni dei vecchi team di sviluppo sono ancora in circolazione, e in origine il piano era di farci da mentori e portarci a pieno regime. Dopo un'indagine rapida, è stato determinato che questo progetto soffre di quanto segue:

Nessun framework di test. Tutto viene testato manualmente a livello di integrazione e spedito al cliente per verificare le modifiche.
Nessuna documentazione di progettazione aggiornata.
Materiale didattico limitato. Il codice fa un sacco di cose non standard (un sacco di uso di file di configurazione che definiscono il comportamento aziendale, l'uso di più file di configurazione per la GUI [attributi della GUI possono essere impostati nel file A.extenion_x o B.extension_y, ma non reale chiaro perché]]

Quello che sto cercando di fare è un elenco di cose che i nostri sviluppatori possono fare mentre lavorano per insegnare agli altri membri del team o ai futuri membri del team. Fondamentalmente voglio solo che loro documentino il loro apprendimento e quindi archivino quelle informazioni.

Fortunatamente il progetto ha sfruttato il software di tracciabilità dei problemi, quindi ogni bugfix o modifica delle funzionalità può essere associata a un identificativo univoco. Possiamo quindi archiviare il materiale didattico e legarlo insieme allo stesso id. Un esempio di detto materiale didattico, sarebbe una rapida descrizione del cambiamento, un piano di test e altre informazioni applicabili al cambiamento.

Al di fuori del ricorso al test delle unità (questo è l'obiettivo, ma non sarà possibile completarlo a breve termine), quali sono altri modi in cui possiamo generare documentazione di apprendimento come parte del nostro processo di sviluppo.

c++ documentation

posta Triplell89 01.10.2015 - 16:46

fonte

1 risposta

Leggi altre domande sui tag c++ documentation

Lettura usando IO non bloccante su un file system in modo asincrono in C ++ (passando da Node.js) Eliminazione di sottoalberi in aggregati gerarchici

score 3 · Accepted Answer

Prima di tutto, hai centrato la testa: Michael Feathers porta a casa il punto di volta in volta quel codice legacy è codice senza test unitari e questo deve essere prioritario quando si lavora su progetti legacy.

Oltre a ciò, fai anche emergere i tracker dei problemi. Non sono sicuro che siano utili nel contesto dell'addestramento e della documentazione.

Mi concentrerei sull'architettura . Qualsiasi progetto abbastanza grande da giustificare questa quantità di lavoro avrà un design di alto livello costituito da moduli (a meno che non sia veramente una grossa palla di spaghetti).

Avrei un approccio a due punte:

I membri senior del team precedente che conoscono il prodotto devono elaborare una documentazione di alto livello che descriva i punti chiave del software dal punto di vista di uno sviluppatore che lavora sul software. Questo dovrebbe essere molto conciso, e precisamente fino a quando deve essere. Dovrebbe essere scritto in modo tale che uno sviluppatore nuovo al progetto abbia un contesto sufficiente per iniziare, ma non è sopraffatto e annegato nella documentazione.
I tuoi sviluppatori che stanno prendendo in carico il progetto devono documentare ogni problema non banale che incontrano e come lo hanno risolto. Sono occhi nuovi che non hanno familiarità con il software: le probabilità sono se sono inciampati da qualcosa, così sarà qualcun altro. Idealmente, questo sarebbe etichettato con la documentazione precedente: uno sviluppatore legacy documenta il modulo XYZ ad alto livello e i nuovi sviluppatori aggiungono le proprie lezioni apprese dal trattare con il modulo, modificandolo in un unico documento coeso (e conciso!).

L'obiettivo finale dovrebbe essere un documento sintetico ma utile che possa portare gli sviluppatori alla velocità del prodotto software.

Probabilmente inserirò la documentazione in un MediaWiki o qualcosa di simile ad esso.