Gli schemi (template) raccolti in questa collezione mirano ad offrire un aiuto al conseguimento di un buon grado di uniformità e completezza nella documentazione di corredo a prodotti software maturi, realizzati in progetti di Architettura degli elaboratori, nonostante le prevedibilmente molteplici differenze fra i prodotti.
Gli schemi sono organizzati per permettere una rapida pubblicazione del software e della documentazione prodotta, sia in versioni preliminari (possibilmente incomplete) che in versione finale, nello spazio web del progetto sul server Galileo. Per le versioni preliminari, se si desidera riservare l'accesso ai componenti del gruppo si possono usare in alternativa il repository SVN e/o il Wiki del progetto sullo stesso server.
Si prevedono due tipologie principali di progetti e, ortogonalmente, due schemi di distribuzione dei relativi prodotti, il che dà luogo a quattro varianti della directory radice, a partire dalla quale gli schemi vanno istanziati per realizzare la documentazione essenziale sui prodotti distribuiti.
Con riguardo agli schemi di distribuzione (dei contenuti, nella subdirectory download), si prevedono due opzioni:
Con riguardo alle tipologie di progetti, si distingue fra:
Naturalmente, possono sussistere progetti di tipologia o con schema di distribuzione diversi da quelli qui contemplati. Si invitano gli studenti ad adottare gli schemi più prossimi alle proprie esigenze, adattandoli a esse ma mantenendo fermo l'obiettivo di non far mancare, pur se diversamente organizzata, la documentazione minima, qui schematizzata attraverso varie note.
N.B. Questo è più importante del rispetto della presente struttura di documentazione e distribuzione: se ne può preferire una diversa per per buoni motivi, e.g. mantenere la struttura di una versione precedente del prodotto, ma il contenuto minimo di documentazione deve in ogni caso essere reso disponibile ai destinatari del prodotto.
La combinazione ortogonale delle due suddette opzioni dà luogo alle quattro subdirectory seguenti, ciascuna delle quali può fungere da directory radice di una istanza di questi schemi:
Nella directory radice, prescelta fra le quattro suddette, vanno istanziati i file-schema index.html e index-en.html (versione inglese del precedente: non si richiede che la documentazione sia bilingue, che comunque raramente lo sarà tutta, ma è utile che lo sia almeno la 'vetrina' di presentazione del prodotto). L'istanziazione è facilitata dalla seguente convenzione:
Stringhe di testo nello schema delimitate da una coppia di caratteri
di sottolinea ("_") sono variabili di schema, che vanno rimpiazzate
(sottolinea incluse) da stringhe appropriate all'istanza.
Si suggerisce di visualizzare il file-schema index.html prima di procedere alla sua istanziazione, così ci si rende subito conto delle poche modifiche da apportare. La visualizzazione può essere effettuata con un navigatore seguendo il link relativo allo schema di interesse:
La commutazione di lingua può essere effettuata puntando il mouse sulla bandierina in alto a destra, mentre le altre tre icone in basso a destra servono alla verifica on-line della conformità agli standard HTML e CSS e alla visualizzazione delle condizioni di licenza libera (GPL v. 3).
La verifica di conformità è importante, non tanto per gli schemi forniti (già verificata), quanto per le loro istanze, che potrebbero essere non conformi per qualche disattenzione nell'editing.
Valgono in generale (e non solo per le istanze dello schema in questione) le seguenti prescrizioni importanti:
Si raccomanda pertanto, ad esempio, di evitare di produrre file HTML mediante mera esportazione da programmi di editing (e.g. Word) noti per produrre disastri rispetto al requisito di conformità qui prescritto. Gli autori di documenti HTML possono verificarne on-line la conformità allo standard anche senza averli pubblicati su web. Questo servizio è disponibile al sito:
http://validator.w3.org .
Il servizio permette il caricamento del file HTML da verificare ("Validate by File Upload"). Lo stesso vale per la verifica di conformità CSS, non necessaria per lo stile impiegato negli schemi qui forniti, ma che può esserlo in caso di adozione di stili diversi. Il sito di questo servizio è:
http://jigsaw.w3.org/css-validator .
Gli altri file-schema qui forniti (oltre a icone, stili CSS ecc.), tutti collocati nella subdirectory doc/ della radice prescelta, sono in formato testo semplice.
Tranne il file license.txt, che non va modificato, i file di testo nella directory doc/ contengono linee guida relative al contenuto minimo dei rispettivi tipi di documento, e in qualche caso anche a eventuali ulteriori contenuti desiderabili. Non è necessario fornire tali informazioni in formato testo semplice: i contenuti dei presenti schemi sono rivolti agli autori, non agli utenti dei prodotti. Gli autori possono scegliere anche altri formati, ma nel caso di tali scelte, e/o di diversa collocazione dei file di documentazione, occorre coerentemente modificare i collegamenti locali nei file index.html e index-en.html, nella directory radice prescelta.
I formati raccomandati per i file di documentazione sono .txt, .html e .pdf. Per il formato .html, valgono i requisiti di conformità W3C stabiliti sopra, mentre:
Per il formato .txt, va rispettata la conformità della codificaSoddisfare questo requisito mette al riparo da differenze di codifica testuale che caratterizzano le più comuni piattaforme, per esempio rispetto a caratteri con segni diacritici (accenti ecc.), nella visualizzazione del file di testo attraverso un navigatore o altro programma di lettura che riconosce UTF-8.
di carattere allo standard UTF-8.
Quando tutti i contenuti sono pronti, incluse le istanze degli schemi indicati, occorre procedere alla costruzione degli archivi da inserire nella subdirectory download/. Per tutti gli archivi in questione è preferibile il formato di compressione .zip, il più diffuso fra sistemi diversi, sebbene non il più efficiente quanto a rapporto medio di compressione. Inoltre, la decompressione di ciascun archivio dovrebbe generare un'unica cartella che contiene tutto il resto. Per esempio, se in un sistema Unix "radice/" è la directory radice dell'archivio da generare, ciò può ottenersi eseguendo nella directory che contiene "radice/" il comando
zip -r radice.zip radice
Alcune delle distribuzioni previste, e certamente quella completa, prevedono l'inclusione della documentazione nella distribuzione. In tal caso la radice dell'archivio dovrebbe contenere una copia esatta della subdirectory doc/ con i suoi contenuti. Si raccomanda di non usare link simbolici a tal fine: zip non li riconosce, e soprattutto la documentazione in una distribuzione deve essere consultabile indipendentemente dalla sua presenza in un contesto esterno, quale in questo caso è la directory doc/ rispetto a download/, che contiene la/e distribuzione/i del prodotto.
Gli schemi qui proposti sono una seconda approssimazione, perfettibile come tutte le cose umane. Commenti e suggerimenti in base all'esperienza d'uso che se ne fa sono molto apprezzati, e possono essere comunicati e discussi nel Forum dell'insegnamento, in risposta al post di apertura del relativo topic. Eventuali nuove versioni di queste distribuzioni saranno rese disponibili allo stesso modo, ovvero via download dalle rispettive pagine degli schemi di documentazione di cui sopra.
Data: Lunedì 5 Aprile 2021
Autore: G. Scollo .
Insegnamento: Architettura degli elaboratori e Laboratorio .
Versione: 0.9
Progetto linee-guida AE 2019 .
Formati di questo documento: Testo semplice , HTML , PDF .