Cosa devo aspettarmi da una guida per sviluppatori? [chiuso]

Una buona guida per gli sviluppatori dovrebbe essere in grado di guidare gli sviluppatori che desiderano utilizzare il tuo prodotto / libreria.

• Dovrebbe fornire loro una panoramica di quale prodotto / libreria è.
• Dovrebbe avere una panoramica di tutti i concetti speciali necessari per usarlo. Ad esempio, se hai una libreria che crea documenti formattati di un tipo molto specifico, una panoramica della struttura del documento potrebbe essere una buona idea. Se si tratta di una libreria di rendering grafica, sarebbe utile una panoramica della pipeline di rendering.
• Dovrebbe contenere un elenco completo di tutti i componenti pubblici (classi, funzioni, qualsiasi cosa) che uno sviluppatore potrebbe utilizzare. Javadoc può probabilmente generare tutto questo.
• Sono anche molto utili esempi di usi comuni della programmazione con il prodotto, inclusi esempi di codice di lavoro.
• Istruzioni speciali per l'installazione / Introduzione allo sviluppo.

Un modo per pensarci potrebbe essere quello di mettersi nei panni degli utenti target e chiedersi cosa tu vorresti vedere se sapessi nulla su questo prodotto e improvvisamente ha dovuto scrivere il codice per questo.

Alcune cose che cercherò in una libreria o in un programma:

1. Che cosa fa e a che scopo è destinato. Hai detto che è un sistema di punti vendita, ma che ancora non mi dice esattamente quali sono le caratteristiche del prodotto.

2. Una guida all'installazione in modo da poter avviare e far funzionare il sistema. Punti bonus se mi dai un processo automatizzato che farà questo per me, quindi non ho dedicato molto tempo alla configurazione.

3. Qualsiasi concetto di dominio che potrebbe essere necessario per capire il sistema. Un glossario di termini può essere utile.

4. Una specifica sarebbe anche buona. Sapere che un sistema fa Foo perché è supposto e non come un incidente felice è utile.

5. Esempi di codice del suo utilizzo o modi per estenderlo. Se è estensibile o in grado di essere integrato, un esempio di estensione \ integrazione è molto istruttivo su come potrei utilizzare il sistema.

6. Infine, diagrammi di architettura e una panoramica del / i codice / i.

Vorrei inserire in tale guida una panoramica dell'architettura e delle regole di codifica (come questi ). Alcune istruzioni di costruzione (come questo) , alcune "contribuiscono come fare" (come questo ).

^{Ho fornito un esempio tramite link relativi a GCC per spiegare cosa intendo. Non ritengo che sia l'esempio migliore.}

Non sono sicuro che UML porterà molto (e quindi dovresti mantenere l'UML).

Soprattutto se il tuo software è una libreria o è estendibile tramite plugin, fornisci alcuni esempi di codice (come usare quella libreria o un tipico plugin).

Il più importante è rimanere sincronizzati con il codice base.