Devo includere una spiegazione sul framework utilizzato in una documentazione del programmatore?

0

Nel mio intership ho usato il framework D3.js per visualizzare i dati, ora alla fine dello stage scriverò una documentazione sul progetto nel suo complesso. Solo poche persone nel mio team sono state coinvolte nel progetto. Nessuno di loro è stato coinvolto nella scrittura di JavaScript. Per quanto ne so non molti sanno come scrivere (buono) JavaScript. Dato che ero relativamente nuovo a JS, probabilmente non ho scritto il codice migliore e a volte ero piuttosto confuso dall'approccio D3.js per unire i dati.

Dovrei provare a spiegare come funziona il binding dei dati in D3.js (Eventhough I potrebbe sbagliare) o dovrei semplicemente fare riferimento a documentazione ufficiale ?
C'è qualche vantaggio se provo a spiegarlo? Per esempio. qualcuno che conosce JS meglio di me vede perché ho fatto qualcosa nel modo in cui l'ho fatto e posso correggerlo / migliorarlo?

Non sto parlando di documentazione in linea. È una documentazione esterna, che dovrebbe spiegare tutti i componenti, le tecnologie, ecc. Esempio: Come funziona l'integrazione di Java, JavaFX e JavaScript?

    
posta Peter 30.09.2016 - 10:13
fonte

2 risposte

2

Secondo me:

  • prima di tutto, dovresti mettere informazioni quali librerie / framework hai usato nella tua applicazione (nome, numero di versione, url a tale libreria)
  • dovresti anche descrivere come funziona la tua applicazione, come è organizzato il codice, quali metodi / funzioni hai usato ecc. Quindi dovresti dare una descrizione generale dei tuoi lavori e la tua idea dietro l'applicazione (ricorda di mettere alcuni schemi / schermate - non solo testo non elaborato)
  • ma non ha senso spiegare come funziona D3.js o qualsiasi altra libreria / plugin / framework. Questo può essere controllato nella documentazione ufficiale.

A proposito. è anche utile utilizzare alcune soluzioni per la documentazione del codice, ad esempio: link

    
risposta data 30.09.2016 - 17:04
fonte
5

Non spiegare come funziona il framework. Questo è già fatto nella loro documentazione ufficiale (supponendo che ne abbiano uno buono).

Invece, dovresti spiegare come stai usando, supponendo che la persona che legge la documentazione abbia letto la documentazione del framework.

    
risposta data 30.09.2016 - 11:32
fonte

Leggi altre domande sui tag