Cosa includere in un rapporto sull'implementazione del software e in che modo?

Secondo me ci sono due cose importanti nella documentazione del software / rapporto:

• Documentazione tecnica, per ogni funzione / classe che descrivi l'input e l'output e cosa fa. Questo potrebbe anche includere la gerarchia delle classi se si utilizza l'orientamento agli oggetti.
• Documentazione utente: include cose come:
  • Qual è l'obiettivo della libreria, quali sono i requisiti
  • Come e perché hai progettato la biblioteca in un modo particolare. Quali schemi di progettazione hai utilizzato (in caso di OOP) o perché hai ordinato le tue procedure in un certo modo. Per il tuo professore questo è anche importante se vuole vedere se riesci a pensare ad un alto livello di astrazione, e non solo nei dettagli nitidi.
  • Esempi di utilizzo (tutorial) che mostrano alcuni buoni esempi di come la libreria può essere utilizzata. Puoi ricollegarti alle decisioni di progettazione e sottolineare che questo esempio mostra perché è stata una buona idea progettare in un modo particolare.

Leggendo l'ultima frase, probabilmente devi descrivere cosa fa la libreria, invece di come lo fa. Includere i campioni è una buona idea; molti studenti dimenticano di farlo, quindi probabilmente avrai punti addizionali per farlo. Inoltre, potresti voler:

• Scrivi documentazione. Gli esempi sono fantastici per scoprire la libreria, ma troppo difficili da usare per trovare una cosa specifica. Inoltre, i campioni tendono a non mostrare mai le caratteristiche che esistono, ma sono usate raramente.

• Alcune indicazioni su in che modo la libreria è implementata possono ancora essere pertinenti. A volte è inevitabile che la libreria venga utilizzata in modo efficiente.

  Esempio: la tua libreria ha il seguente metodo:

  // Adds words from a single source to a dictionary.
  void AddToDictionary(Source dataSource);
  
  // Adds words in parallel from multiple sources to a dictionary, while opening
  // and saving the dictionary only once.
  void AddToDictionary(IEnumerable<Source> dataSource);
  

  Senza una documentazione adeguata, non sarei in grado di sapere che devo usare il secondo sovraccarico per quattro o più dizionari e seguire la prima implementazione di base per uno o tre dizionari, perché la tua libreria è implementata in modo tale che il l'attività parallela sarà efficace solo con un numero elevato di librerie: con meno, il tempo di caricare e salvare il dizionario più volte sarà troppo piccolo.

• Ultimo ma non meno importante, quali sono i requisiti per la tua libreria? Se è scritto in .NET Framework, ho bisogno di .NET Framework 3.5? 4? 4.5? Come distribuirlo? Semplicemente scaricando il file? Scaricando l'installazione e eseguendola? Prendendo il pacchetto e facendo cento passi per farlo funzionare?