Documentare un linguaggio di programmazione: Manuale di riferimento

Stiamo esaminando la documentazione di rinnovamento della nostra linea di prodotti. Parte di ciò include manuali di riferimento per un linguaggio di programmazione utilizzato come parte del sistema.

Quando si scrive un manuale di riferimento per un linguaggio di programmazione, qual è il modo migliore per strutturarlo per la massima usabilità per chi non conosce il linguaggio?

Quali sono gli aspetti chiave per ogni parola chiave documentata?

• Sintassi
• Descrizione
• Argomenti - se applicabile
• Valori di restituzione - se applicabile
• Esempio di utilizzo?
• Qualcun altro mi manca?

Concetti (come strategie di blocco, dettagli relativi alle prestazioni) dovrebbero essere documentati anche in questo manuale di riferimento o è un documento separato?

_{Questo è per consumo esterno. Abbiamo già set di documenti completi (consultare: http://www.rocketsoftware.com/u2/resources/technical-resources ). Risolvendo ciò che dovremmo fare diversamente: ho già le mie idee, ma come sempre, cerco di non fare affidamento esclusivamente sulla mia opinione.}

_{Pubblico: sviluppatori tecnici che utilizzano i nostri database e strumenti per produrre software in molti settori.}

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

Nel tuo caso, il pubblico primario è apparentemente sviluppatori di software. Le parti da considerare qui sono indirizzate a diversi "sotto-audience" di questo:

1. Ciao mondo.
   Coloro che sono disposti a prenderne rapidamente il gusto, creano ed eseguono un'applicazione di esempio per vedere come appare.
   Pensa al pubblico come quello affrontato da MySQL "Regola dei 15 minuti" :
   

   _{... un utente per avere MySQL attivo e funzionante 15 minuti dopo aver finito di scaricarlo.}

2. Fondamenti.
   Per i ragazzi disposti a imparare rapidamente le cose necessarie per iniziare a produrre software funzionante.
3. Argomenti avanzati.
   Per gli sviluppatori che hanno già dimestichezza con i fondamenti, sono interessati a sapere cosa c'è oltre. Argomenti tradizionali che non sono stati trattati in Fondamenti .
4. Guida di stile / Pratiche consigliate.
   Consulenza soggettiva e orientamento per coloro che sono interessati al modo in cui consigli di fare le cose.
   _{La domanda non indica se questo potrebbe avere un pubblico sostanziale nel tuo caso, quindi le opzioni da considerare sono includerlo come parte / appendice degli argomenti avanzati o addirittura lasciarlo cadere completamente.}
5. Quirks.
   Argomenti oscuri, al di fuori del mainstream, che potrebbero interessare una frazione piuttosto limitata del tuo pubblico. Ad esempio, se hai una linea legacy o cose come l'aggiornamento / migrazione / interoperabilità con legacy, inseriscilo qui. Se ci sono alcuni effetti collaterali per alcune funzioni in un particolare ambiente "esotico", va da questa parte.

^{E se qualcosa nel manuale fosse discutibile / ambiguo? E se si scoprisse che una spiegazione approfondita di concetti particolari renderebbe quel manuale troppo difficile da leggere? Cosa succede se si scopre che quella particolare versione del manuale presenta degli 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ò fare riferimento a un particolare paragrafo nelle specifiche per una dichiarazione rigorosa e chiara, "ufficiale" al riguardo. Una descrizione rigorosa e completa (e molto probabilmente noiosa) della sintassi del linguaggio sarebbe meglio andare lì.
   Considerazioni fondamentali per le specifiche sono l'accuratezza e la completezza tecnica, anche se queste vanno a scapito della leggibilità.
2. Supplemento online.
   Basta riservare un po 'di URL e inserirlo all'inizio di ogni documento che rilasci, in modo che i ragazzi che si chiedono cosa diavolo hanno appena letto possano andare lì (invece di infastidire i manutentori manuali) e trovare l'errore spiegato.

   _{Errata> Fondamenti> Release 2.2> Errore di battitura a pagina 28, la seconda frase inizia con fortuna , leggi invece il lucchetto .}

Ad esempio, i manutentori manuali sarebbero interessati a una descrizione completa e accurata della concorrenza e al blocco delle specifiche formali, mettetele 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. Scopo di questo studio facendo leva sull'esperienza acquisita da coloro che l'hanno fatto prima e imparando a evitare errori commessi.}

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

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

La seconda cosa che devi valutare è la granularità dei primitivi della lingua. Quanto più fine è la granularità, tanto 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 crea un'istanza di 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 vicino- nel manuale. Consulta la documentazione di openssl online per un eccellente esempio di documentazione quasi inutilizzabile.

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

In ogni caso, se non vuoi che i programmatori dei tuoi clienti ti malediscano ogni sera 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 fatto distinzione tra manuali di riferimento e guide per l'utente . Il manuale di riferimento di solito include le specifiche della sintassi, una definizione intelligibile delle funzioni o delle primitive, discussione di gotcha, prestazioni ed 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 "linguaggio di programmazione C" di Kernigan e Ritchie è un eccellente contro-esempio di questa convenzione, ma questo approccio funziona solo quando la lingua che stai documentando è relativamente semplice.

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