Qual è il modo migliore per dimostrare che la documentazione in codice è superiore alla documentazione esterna estesa?

Tutto dipende dallo scopo della documentazione.

Due casi GENERALI:

1. Documentare il funzionamento interno di un pezzo di codice, giù nei bit del gory e negli algoritmi - le cose che non sono importanti per un mondo esterno perché sono nascoste sotto un'astrazione o dietro un'API - è probabilmente il migliore nel codice. Perché fuori dal codice che nessun altro conosce o cura.

2. Le cose che vanno oltre - API, principi generali di progettazione, definizioni di interfacce, messaggi scambiati e così via - sono una questione diversa. Questi dovrebbero essere definiti in dettagli dolorosi in documenti esterni. E solo cambiato più tardi - con la benedizione di dio.

Per API non intendo ciò che appare in un file di intestazione C, o qualche definizione di classe (anche se le linee si stanno sfocando). Di solito può essere gestito bene nella fonte.

Ci saranno dei gradi nel mezzo che richiedono pensiero.

Forse alcuni esempi potrebbero aiutare:

• L'algoritmo che usi per calcolare i giorni tra le date dovrebbe essere documentato nel codice.

• Il sistema di trasferimento messaggi multiprocessore definito con ridondanza di failover e porting di processo in fase di esecuzione deve essere documentato nei documenti.

• L'architettura dei plugin per il tuo nuovo sistema di controllo dei veicoli senza conducente (sai, quello che ti permette di aggiungere un nuovo modulo di volo in fase di runtime senza riavvio), dove i plugin sono sviluppati da un'azienda esterna - beh, la documentazione nella sola fonte sarebbe molto problematica, utilizzare un documento con parole che descriva interazioni, dipendenze, ordini di tempo, trucchi, eccezioni, limitazioni e così via. Con diagrammi Tutto in un unico posto.

Hai avuto l'idea - ci sono dei gradi per queste cose, e le ragioni per andare in entrambi i modi. Prendi una decisione intelligente e ponderata.

Non sono destinati a fare la stessa cosa. Certo, potrebbe esserci qualche sovrapposizione, ma in generale la documentazione in codice sarà a un livello inferiore che descrive cosa fa questa sezione del codice, mentre la documentazione esterna sarà migliore per descrivere l'applicazione ad un livello superiore, o addirittura nel suo complesso, oltre lo scopo di un solo file di codice.

Direi che non si tratta dell'una o dell'altra. Entrambi dovrebbero essere usati.

Potresti pensare che il codice sia "auto-documentante", ma posso assicurarti che ti sbagli. L'unica ragione per cui pensi che sia, è perché hai la conoscenza di come il tuo codice funziona nascosto nella tua testa - è come avere un insieme invisibile e non scritto di documentazione memorizzata. Lavora sul codice di qualcun altro e inizierai a vederlo (di solito questo si manifesta come la sindrome di "i miei colleghi codice è una schifezza", in realtà è solo perché ti manca tutta la documentazione su come funziona).

La documentazione "esterna" è tanto importante quanto il codice, devi essere in grado di comunicare ciò che fa il codice, come lo fa (in termini di progettazione generale) e perché lo fa. Queste cose non possono essere incorporate nella base di codice a grana fine. Certo, puoi anche fare i documenti di codice interno, e possono essere generati automaticamente, ma li ho sempre trovati un po 'inutili rispetto alla sola lettura del codice (e dei commenti incorporati).

Dove hai ragione è che la documentazione non deve essere un compito faticoso, scritto in enormi documenti di Word. È possibile semplificare l'operazione scrivendola in un linguaggio di marcatura leggero (ad esempio ASCIIDoc o ReStructured Text) che può quindi essere compilato in formati Word o HTML. Questa documentazione "sorgente" può essere modificata all'interno del tuo IDE in quanto sono solo file di testo, e puoi anche applicare gli strumenti di revisione del codice e il tuo SCM. Questo approccio rende l'attività di documentazione necessaria notevolmente più semplice per i team di sviluppatori.

Penso che tu debba essere un po 'nel mezzo. Pubblici diversi richiedono diversi livelli e stili di documentazione.

I tuoi peer SAP potrebbero essere esagerati per il consumo dello sviluppatore, ma immagino che la loro documentazione passi piacevolmente nelle pagine di aiuto o in una guida per gli utenti. I commenti sul codice non aiutano a vendere l'applicazione alla gestione nelle fasi iniziali. I requisiti e i documenti di progettazione di alto livello non si adattano bene al codice, ma sono certamente fondamentali per la comprensione da parte di tutti del comportamento corretto / previsto.

È possibile generare file di aiuto dai commenti XML nel codice sorgente. SandCastle può prendere quelli commenta e crea file di aiuto carini, che puoi integrare con la documentazione concettuale.

MODIFICA: gli strumenti ti consentono di:

1. Porta i tuoi commenti sul codice a una documentazione esterna
2. L'origine dei tuoi documenti è versionata, senza ulteriore sforzo (poiché il tuo codice sorgente è già presente, giusto?)
3. Se hai bisogno di spiegare concetti ai nuovi sviluppatori, l'app project manager di documenti ha un editor (semi-decente) per i cosiddetti "documenti concettuali" in un linguaggio basato su XML. Mi sono abituato, l'editor è abbastanza buono da non essere un problema.
4. Non ricordo i dettagli della memoria, ma credo che tu possa collegare tra loro tutto ciò (contenuto basato su codice e concettuale), permettendoti di ottenere qualcosa in linea con l'aiuto di VS.

Tutto ciò ti consente di ottenere tutto il contenuto da ciò che già esiste nelle tue fonti e di completarlo con spiegazioni concettuali (il "come tutto ciò si adatta al puzzle?"). E avendo la possibilità di esportarlo in HTML, Aiuto CHM e altri formati. Credo che placherà la tua esigenza di gestione della documentazione esterna dagli interni.

EDIT 2: Rispondendo al secondo montaggio dell'OP, ciò che sta cercando è una sorta di registro delle modifiche per rispondere perché (e quando) sono accaduti alcuni cambiamenti.

Potresti implementarlo sul codice o su un oggetto "contenuto concettuale" esterno che puoi modificare (o generare) dai ganci del sistema di controllo sorgente. In questo modo, ogni volta che generi la documentazione, ottieni il documento "Cosa c'è di nuovo in questa versione" in un formato facilmente presentabile.

Può anche essere un file di progetto di documentazione diverso dal progetto principale di Documention (il che significa che può essere generato separatamente e con diverse impostazioni di presentazione).

A proposito, sembra che il tuo capo stia cercando un modello da seguire. Il processo SAP sembra troppo, ma puoi mostrargli cosa sta cercando di ottenere (che è la tracciabilità delle modifiche: la domanda "chi, quando e cosa") in modo automatico (e presentabile).

PS .: Anche in questo caso sarebbe utile un sistema di tracciamento dei bug, in quanto è possibile includere anche la richiesta di modifica (o il file del bug #) che ha motivato la modifica.

What is the best way to prove to my boss that in code documentation is greater than extensive external documents containing documentation and screenshots of code/ui?

Potrebbe essere, ma non è una regola. Per che cosa sarà usata la documentazione? (Chi lo accede? Quanto spesso? Quale feedback / decisioni vengono fuori da tale attività?)

Their documentation process involves hours of laborious documentation and screenshots of the code and the interface (before and after).

Would you really want to have to screenshot your code before and after every single baby change and then write a document explaining the change in great depth?

Sembra che stiano facendo male '* - non hanno bisogno della tua documentazione - hanno bisogno di una nota da qualche parte, dicendo:

git/hg/svn/xyz diff -rXXXX -rYYYY # show code differences
git/hg/svn/xyz info XXXX          # show change description and details

o qualcosa di simile. Questo può essere facilmente automatizzato da qualsiasi SCM valido, o con qualsiasi cosa siano chiamati i deliverable ("release di funzionalità", "richieste di modifica", "rapporti finali di iterazione", "commit pubblici", "difetti risolti", ecc.)

when no one will ever use these documents as reference material in the future?

Se davvero nessuno li userà mai, allora è facile dimostrarlo: nessuno li userà mai. Puoi parlare con loro per scoprire se è davvero così?

'* - Non sono sicuro che lo stiano facendo davvero male. Dipende da cosa viene usata questa documentazione.