11.1 Direttive alla documentazione

Quando ci sono dei cambiamenti radicali nel codice da parte dell'utente, DEVE essere documentato ogni novità in ogni appropriata locazione.

2.  Quando apportiamo una modifica al file di congurazione, ed è compatibile con la versione precedente DEVE essere documentato in example.conf e in file README.NOW. Questo è veramente importante durante la fase di BETA Test per aiutare a tutti a cercare nell' "help desk".

3.  Tutta la documentazione deve essere visibile correttamente in un terminale largo massimo 80 caratteri. L'SGML e altri sistemi di documentazione "professionali" sono buoni per alcuni progetti, ma Hybrid è progettato per essere utilizzato su installazioni minime di UNIX dove qualsiasi  binario extra è un rischio per la sicurezza. Perciò i nostri documenti dovranno essere solamente testuali ed adatti ad una console di 80 caratteri, questo è tutto ciò chegli admins pretendono ed è quello che vorrebbero ottenere.

4.  Su tutta la documentazione deve essere fatta il controllo ortografico prima di un rilascio o di una beta. 'ispell'( utilizzando l'uno o l'altro il dizionario americano o britannico o nel nostro caso italiano ) è
    probabilmente il modo più facile per eseguire il controllo ortografico della documentazione. 'ispell-a' dalla riga di comandi vi permetterà di controllare singole parole durante la digitazione.

5.  Quando un documento finito è lungo circa 5 pagine,  dovrebbe essere suddiviso in sezioni per agevolare gli utenti alla lettura.

6.  Tutti i documenti (se non speficicamente discritti nel codice) dovrebbero essere scritti in un modo che cui tutti gli utenti del software (non solo programmatori) siano in grado di capire facilmente il funzionamento delle modifiche.

7.  Non fate un lavoro ingrato di documentazione. Documentando singole parti di solito si è più precisi. La documentazione non vi terrà impegnati a lungo e non scordate di aggiornare i vostri manuali accumulando lavoro arretrato.

8.  Non dimenticare di includere l'id del CVS.

 

Questo, ed altri documenti, possono essere scaricati da http://doc.ircd-hybrid.it.

Per domande su ircd-hyrbid, leggi la documentazione prima di contattare <doc@ircd-hybrid.it>.
Per domande su questa documentazione, invia una e-mail a <doc@ircd-hybrid.it>.