Documentazione di un linguaggio di programmazione: Manuale di riferimento

Organizza la documentazione in base alle esigenze del pubblico di destinazione.

Nel tuo caso, il pubblico principale è apparentemente uno sviluppatore di software. Le parti da considerare qui sono per indirizzare diversi "sub-segmenti di pubblico" di questo:

1. Ciao mondo.
   Quelli disposti a ottenere rapidamente il gusto di esso, basta compilare ed eseguire un'applicazione di esempio per vedere come appare.
   Pensa al pubblico come a uno di MySQL "regola dei 15 minuti" :
   

   _{...a user to be able to have MySQL up and running 15 minutes after he finished downloading it.}

  
2. Fundamentals.
     Per i ragazzi disposti a imparare rapidamente le cose necessarie per iniziare a produrre software di lavoro.
  
3. Argomenti avanzati.   Per gli sviluppatori già ben conosciuti e praticati con i fondamentali, interessati a sapere cosa c'è oltre. Argomenti principali che non sono stati trattati in Nozioni di base .
  
4. Guida allo stile / Procedure consigliate.
     Consulenza soggettiva e guida per coloro che sono interessati al modo in cui si consiglia di fare le cose.
   _{La domanda non indica se questo potrebbe avere un pubblico rilevante nel tuo caso, quindi le opzioni da considerare sono di includerlo come parte / appendice di Argomenti avanzati o addirittura rilasciarlo completamente.}
  
5. non standard.
     Argomenti oscuri, al di fuori del mainstream, che potrebbero interessare una parte piuttosto limitata del tuo pubblico. Ad esempio, se hai legacy line o cose come upgrade / migration / interoperability con legacy - mettilo qui. Se ci sono alcuni effetti collaterali per alcune funzioni in particolari ambienti "esotici", va in questa parte.
  

  Il tuo pubblico secondario è il manutentore del manuale. Questi ragazzi possono creare o distruggere il modo in cui le cose funzionano per il tuo pubblico principale, quindi è meglio prenderti cura dei loro bisogni e problemi.

^{Cosa succede se qualcosa nel manuale è discutibile / ambiguo? E se risultasse che una spiegazione approfondita di concetti particolari renderebbe troppo difficile leggere quel manuale? Cosa succede se risulta che una particolare versione del manuale ha errori?}

Due cose da considerare per i manutentori sono:

1. Specifiche tecniche / formali.
   Ogni volta che c'è un argomento discutibile / ambiguo / difficile da spiegare nel manuale, il lettore può essere indirizzato a un particolare paragrafo nelle specifiche per una dichiarazione "ufficiale" rigorosa e chiara a riguardo. Una descrizione rigorosa e completa (e probabilmente noiosa) della sintassi del linguaggio andrebbe meglio lì.
   Considerazioni di primaria importanza per Specifica sono accuratezza e completezza tecnica, anche se a scapito della leggibilità.
2. Supplemento online.
   Basta prenotare qualche URL e metterlo all'inizio di ogni documento che pubblichi, in modo che i ragazzi si chiedano che diavolo hanno appena letto potrebbero andare lì (invece di infastidire i manutentori manuali) e trovare l'errore spiegato .

   _{Errata > Fundamentals > Release 2.2 > Typo at page 28, second sentence starts with luck, read lock instead.}

  

  Concetti come le strategie di blocco, i dettagli relativi alle prestazioni dovrebbero essere inclusi (possibili parzialmente) in cui ci si aspetta che il pubblico di destinazione ne abbia bisogno.

es. apparentemente, i manutentori manuali sarebbero interessati a una descrizione completa e accurata della concorrenza e al blocco delle specifiche formali - mettetelo lì. I lettori di Fondamenti o Argomenti avanzati potrebbero essere interessati a una panoramica / introduzione / guida estratta dalle specifiche e adattata alle loro esigenze, ecc.

_{Potrebbe essere utile organizzare uno studio comparativo della documentazione di riferimento fornita per altre lingue come la tua. Mira a questo studio sfruttando l'esperienza acquisita da chi l'ha fatto prima e imparando come evitare gli errori che hanno commesso.}

_{L'ultimo, ma non meno importante, considera l'impostazione dello sviluppo della documentazione in modo simile allo sviluppo del software. Intendo cose come controllo di versione, rilasci periodici, tracciamento di problemi, controllo qualità ecc. Potresti voler fare dei compromessi anche se si scopre che i tuoi scrittori tecnici non sono davvero a loro agio con cose del genere. Non vogliamo ottenere "in cambio" contenuti scadenti per un processo di sviluppo perfetto, vero?}

    

La prima cosa che devi fare è valutare il pubblico. È il tuo pubblico hacker del kernel Linux o sono progettisti di hardware che usano strumenti software per fare un lavoro ma non sono interessati al software in sé e non hanno uno sfondo CS. È probabile che gli ingegneri elettrici non siano completamente chiari sulle differenze tra argomenti const e non-const, puntatori a oggetti contro riferimenti, ecc. Se i tuoi primitivi hanno nomi sovraccaricati, allora è meglio spiegare quel concetto ad un livello appropriato per il tuo pubblico, che potrebbe essere nulla se sono programmatori C ++.

La seconda cosa che devi valutare è la granularità dei primitivi del linguaggio. Più fine è la granularità, più sarà necessario fornire esempi di utilizzo in prossimità delle specifiche di sintassi di ciascuna primitiva. Cioè, se hai una primitiva di basso livello che istanzia un contesto, e devi operare su di essa con altre tre primitive di basso livello prima di poter fare qualcosa di utile, allora è meglio avere un esempio completo di qualche utile funzione close- da nel manuale. Consulta la documentazione online openssl per un eccellente contro-esempio di documentazione quasi inutilizzabile.

Assicurati di includere la spiegazione di qualsiasi effetti collaterali delle tue funzioni.

In ogni caso, se non vuoi che i programmatori dei tuoi clienti ti maledichino ogni notte prima di andare a letto, includi un sacco di codice di esempio testato che esegue alcune primitive funzionali di alto livello. Assicurati che gli esempi non siano solo frammenti di codice, ma completi e compilabili o eseguibili immediatamente.

Tradizionalmente, gli scrittori di tecnologia hanno distinto tra manuali di riferimento e guide utente . Il manuale di riferimento di solito include le specifiche di sintassi, una definizione intelligibile delle funzioni o delle primitive, la discussione di gotcha, le prestazioni e gli effetti collaterali e un breve esempio di utilizzo. La guida per l'utente include esempi di utilizzo più estesi e discussioni su problemi di ingegneria più ampi. Il Kernigan and Ritchie "C Programming Language" è un eccellente contro-esempio a questa convenzione, ma questo approccio funziona solo quando la lingua che stai documentando è relativamente semplice.

L'autore è stato responsabile della divisione Servizi di ingegneria presso il centro di sviluppo di Ready Systems Inc tra il 1987 e il 1991 con la responsabilità di gestire un team di cinque scrittori di tecnologia.