Progetto CircuitVerse

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

Riepilogo del progetto

Organizzazione open source:
CircuitVerse
Technical writer:
DVL
Nome progetto:
Consolidamento e miglioramenti dei libri interattivi di CircuitVerse
Durata del progetto:
Durata standard (3 mesi)

Project description

1 Riassunto

CircuitVerse è un progetto open source che mira a fornire una piattaforma in cui i circuiti possano essere progettati e simulati utilizzando una Graphic User Interface basata sul web. Il simulatore di logica può essere utilizzato per progettare fino a completare le implementazioni della CPU, sebbene sia progettato principalmente per uso didattico. Oltre alla documentazione tecnica del software, un libro interattivo online guida l'utente nell'apprendimento della progettazione della logica digitale. Il libro consente all'utente di provare i circuiti direttamente dall'interno del libro per un'esperienza interattiva.

Il libro è in uno stato di sviluppo iniziale e al momento mancano alcune sezioni pertinenti. La struttura generale è lenta in termini di flusso che collega le diverse sezioni e richiede contenuti più dettagliati. Inoltre, secondo l'organizzazione, non ci sono linee guida per aiutare i collaboratori a collaborare al progetto né un piano o una roadmap per guidare i contributi su quali contenuti sono necessari e con quale priorità.

L'obiettivo di questa proposta è collaborare con i mentori per creare linee guida per i contributi, produrre un piano di sviluppo degli argomenti e contribuire al miglioramento dei contenuti attuali e alla creazione di nuovi contenuti in base al piano di sviluppo.

2 Lo stato attuale del libro interattivo

Dal lancio del progetto in Google Summer of Code 2019, il progetto ha avuto una "crescita non gestita ", con l'aiuto della community di studenti. L'organizzazione del progetto è costituita principalmente da sviluppatori, che hanno quindi aderito al GSoD per cercare assistenza esterna al fine di migliorare l'Interactive Book. Gli sviluppatori del progetto hanno rilevato che al momento il libro richiede la riscrittura di alcune sezioni, l'aggiunta di nuovi contenuti e lo rendono più dettagliato e completo. Inoltre, il team si aspetta di avere, dopo il GSoD, linee guida per i nuovi contributi e un "master plan" generale per lo sviluppo dei contenuti.

3 Qual è il contributo di questa proposta

Questa proposta contribuirà alla creazione collaborativa di una prima versione delle linee guida per i contributi, allo scopo di garantire un processo di collaborazione più armonico per i collaboratori, portando così a contenuti più coerenti. Verrà inoltre delineato un piano di sviluppo per gli argomenti del libro. Saranno inoltre previste le aggiunte e le modifiche più urgenti in base al nuovo piano di sviluppo.

4 Analisi delle alternative disponibili

Diversi progetti open source maturi con caratteristiche simili hanno già sviluppato linee guida per i contributi per la documentazione, ad esempio Wikibooks ([Guida:Contributo], [Wikibooks:Policies e linee guida]), OpenStreetMap ([Linee guida di editing organizzate]) o The Linux Documentazione Project ([Guida per gli autori LDP]). Questi esempi possono essere utilizzati per creare le linee guida del progetto basate sull'esperienza di progetti open source di successo.

Per il piano di sviluppo dell'argomento è possibile confrontare i programmi di corsi aperti (ad es. [MIT Open Courseware]) e libri di riferimento sui circuiti di logica digitale, inclusi libri aperti come [Lessons In Electric Circuits -- Volume IV -Digital], [Wikibooks: Digital Circuits] e [Wikibooks: Digital Electronics].

[Help:Contributo] https://it.wikibooks.org/wiki/Help:Contributing

[Wikibooks:Norme e linee guida] https://it.wikibooks.org/wiki/Wikibooks:Policies_and_guidelines

[Linee guida sulla modifica organizzata] https://wiki.osmfoundation.org/wiki/Organised_Editing_Guidelines

[Guida per gli autori LDP] https://www.tldp.org/LDP/LDP-Author-Guide/html/index.html

[MIT Open Courseware] https://ocw.mit.edu/

[Lezioni di circuito elettrico - Volume IV - Digital] https://www.iBiblioteca.org/kuphaldt/electricCircuits/Digital/index.html

[Wikibooks: Digital Circuits] https://it.wikibooks.org/wiki/Digital_Circuits

[Wikibooks: Elettronica digitale] https://en.wikibooks.org/wiki/Digital_Electronics

5 Struttura della documentazione proposta

Il libro interattivo ha il potenziale per essere utile per un vasto pubblico, dagli studenti amatoriali di elettronica amatoriali e degli studenti di scuola secondaria, a studenti dell'istruzione terziaria e professionisti che hanno bisogno di aggiornare o rafforzare le proprie competenze nei circuiti logici digitali.

Per affrontare l'eterogeneità degli utenti del libro, viene proposta una struttura "multi-livello", in cui ogni livello corrisponde a un livello crescente di complessità e profondità teorica dei contenuti.

Pertanto, la struttura della documentazione cresce in due dimensioni: la prima dimensione corrisponde alla sequenza logica o tradizionale di argomenti nei sistemi logici digitali, mentre la seconda rappresenta il livello.

Nel seguente elenco strutturato viene rappresentata la struttura bidimensionale proposta. La sequenza standard degli argomenti viene presentata al livello più alto. Per semplicità, per ogni argomento vengono definiti solo tre livelli di complessità, corrispondenti ai livelli di base, medio e avanzato. Per ogni livello vengono elencati i contenuti relativi all'argomento generale specifico.

  • Rappresentazione mediante numeri binarty:
    • Livello di base: Numeri binari, Quantità negative, Altre basi, Codifica.
    • Livello medio: [nessun contenuto specifico]
    • Livello avanzato: moduli e anelli
  • Operazioni matematiche con numeri binari:
    • Livello di base: addizione, sottrazione, moltiplicazione, divisione
    • Livello medio: algebra booleana, funzioni booleane
    • Livello avanzato: altre algebre, decomposizione di Shannon
  • Componenti SSI combinati:
    • Livello di base: simboli, porte logiche, tabelle di verità
    • Livello medio: famiglie logiche, porte universali
    • Livello avanzato: comportamento temporale (modelli a tempo, pericoli)
  • Design combinato della logica:
    • Livello base: descrizione funzionale, implementazione
    • Livello medio: funzioni canoniche, mappe k-
    • Livello avanzato: variabili inserite nella mappa, Quine McCluskey, rappresentazione di cubi binari
  • Componenti MSI combinati:
    • Livello base: MUX, DEMUX, Encoder, Decoder, Half Adder, Full Adder
    • Livello medio: funzioni basate su MUX
    • Livello avanzato: [nessun contenuto specifico]
  • Componenti LSI combinati:
    • Livello di base: ROM, ALU
    • Livello medio: PLD (PLA, PAL, gal)
    • Livello avanzato: [nessun contenuto specifico]
  • Componenti SSI sequenziali:
    • Livello di base: chiavistelli, infradito, segnali di orologio, diagrammi temporali
    • Livello medio: feedback sulla memoria, sistemi sincroni, sistemi asincroni
    • Livello avanzato: [nessun contenuto specifico]
  • Componenti MSI sequenziali:
    • Livello di base: registri, contatori
    • Livello medio: [nessun contenuto specifico]
    • Livello avanzato: [nessun contenuto specifico]

  • Progettazione sequenziale:

    • Livello di base: [nessun contenuto specifico]
    • Livello medio: sintesi sequenziale, FSM (Mealy, Moore), diagrammi di stato, minimizzazione degli stati, assegnazione dello stato, condizioni di competizione
    • Livello avanzato: design basato su MSI, design basato su LSI, diagrammi di flusso, diagrammi MDS

    Il livello di base dovrebbe consentire agli utenti di comprendere come funzionano i circuiti di logica digitale e come utilizzarli, senza richiedere alcuna conoscenza di matematica superiore. Potrebbe quindi essere adatto agli studenti amatoriali e a studenti di istruzione secondaria di secondo grado. Se questi utenti hanno le competenze necessarie e vogliono approfondire la conoscenza, possono lavorare su alcuni o tutti i contenuti del livello medio.

    Il livello medio dovrebbe essere equivalente per contenuti e requisiti a un corso introduttivo di istruzione terziaria in un sistema logico digitale.

    Infine, il livello avanzato include contenuti che in genere sono disponibili nei corsi avanzati complementari o facoltativi di sistemi digitali nelle università.

    Questa struttura proposta verrà discussa con i mentori nella fase iniziale del progetto (Settimana 3), che verrà poi utilizzata come input per delineare un piano di sviluppo dell'argomento a lungo termine.

    La struttura proposta può utilizzare la maggior parte, se non la totalità, dei contenuti attuali della documentazione, che verranno rivisti e estesi o corretti di conseguenza, se necessario. Inoltre, verranno scritte nuove sezioni per i contenuti che non sono ancora trattati nella documentazione esistente.

6 obiettivi

  1. Produci una prima bozza di linee guida per i contributi per il progetto Interactive Book.
  2. Definisci uno sviluppo degli argomenti del libro.
  3. Riscrivere e ristrutturare i contenuti attuali.
  4. Crea nuovi contenuti in base al piano di sviluppo.

7 Sequenza temporale

Settimana 1: (dal 14 al 20 settembre) analizza e discuti con i mentori le migliori linee guida basate sugli esempi di altri progetti e sull'esperienza maturata finora nel progetto. Settimana 2: (21 settembre - 27 settembre) Scrivi la bozza delle linee guida Settimana 3: (28 settembre - 4 ottobre) Discuti la bozza del piano di sviluppo dell'argomento con i mentori. Settimana 4: (5 Ott. - 11 Ottobre) Scrivi il piano di sviluppo. Settimane dalla 5 all'11: (12 ottobre - 29 novembre) scrivi i contributi, basati su contenuti ristrutturati e argomenti nuovi. Settimana 12: (30 novembre - 5 dicembre) Presentazione della relazione di progetto. Valutazione del progetto: (3 dicembre - 10 dicembre) - Invio della valutazione del Technical Writer. - Invio della valutazione dei mentori.

8 Perché il libro interattivo di CircuitVerse

A causa della crisi globale dovuta al COVID-19, ho iniziato a cercare risorse online che avrebbero aiutato i miei studenti di un corso universitario sui sistemi logici digitali. Sostengo le tecnologie open source Free-Libre da diversi decenni, quindi do la priorità a questo tipo di progetti. Ho trovato il simulatore CircuitVerse e ho deciso che fosse un ottimo strumento per integrare la mancanza di attività di laboratorio a causa delle misure di contenimento del COVID-19 della nostra università. Durante il test del simulatore ho scoperto che il loro libro interattivo non era ancora sufficiente come riferimento principale per un corso completo sui sistemi di logica digitale. I suoi attuali contenuti erano corretti e facili da comprendere, quindi l'ho incluso nelle risorse di apprendimento.

Dato che stavo utilizzando il loro simulatore e prenotavo in modo intensivo, l'organizzazione mi ha contattato per parlarmi della GSoD. Ho intravisto in questo l'opportunità di contribuire al progetto direttamente dalle mie competenze.

9 Riferimenti

  • [Guida Wikibooks:Contributo],
  • [Wikibooks:Norme e linee guida]
  • [Linee guida per la modifica organizzata di OpenStreetMap]
  • [Guida per gli autori di Linux Documentazione Project (LDP)]
  • [Programma MIT Open Courseware Introductory Digital Systems Laboratory Programma di studio]
  • [Lezioni sui circuiti elettrici - Volume IV - Digitale]
  • [Wikibooks: circuiti digitali]
  • [Wikibooks: Elettronica digitale]

  • [The Linux Brochure Project]

    [Guida di Wikibooks:Contributo] https://it.wikibooks.org/wiki/Help:Contributo

    [Wikibooks:Norme e linee guida] https://it.wikibooks.org/wiki/Wikibooks:Policies_and_guidelines

    [Linee guida sulla modifica organizzata di OpenStreetMap] https://wiki.osmfoundation.org/wiki/Organised_Editing_Guidelines

    [Guida per gli autori di Linux Documentazione Project (LDP)] https://www.tldp.org/LDP/LDP-Author-Guide/html/index.html

    [MIT Open Courseware Introductory Digital Systems Laboratory Syllabus] https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-111-introductory-digital-systems-laboratory-spring-2006/syllabus/

    [Lezioni di circuito elettrico - Volume IV - Digital] https://www.iBiblioteca.org/kuphaldt/electricCircuits/Digital/index.html

    [Wikibooks: Digital Circuits] https://it.wikibooks.org/wiki/Digital_Circuits

    [Wikibooks: Elettronica digitale] https://en.wikibooks.org/wiki/Digital_Electronics

    [The Linux Brochure Project] http://lbproject.sourceforge.net/