Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo del progetto
- Organizzazione open source:
- TheGoodDocsProject
- Technical Writer:
- Logomania
- Nome progetto:
- Guida all'architettura dell'informazione
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Piano della guida all'architettura dell'informazione
Questo documento illustra la pianificazione di una guida all'architettura dell'informazione per il progetto Good Docs. È stata preparata nell'ambito dell'invio della stagione di Documenti Google 2020. Delinea il caso d'uso della guida proposta e abbozza un piano della struttura di una guida di questo tipo, a fini di pianificazione.
L'architettura dell'informazione (IA) riguarda l'organizzazione dei contenuti. Copre la struttura dei contenuti senza definire lo stile o le parole utilizzate al loro interno. Ad esempio, un piano di IA prende in considerazione chi è il lettore, come si approccia ai contenuti e l'ambiente in cui legge. Quindi, prenderebbe in considerazione una struttura adeguata per i contenuti più adatta a questi requisiti dei lettori.
In un mondo perfetto, la documentazione è progettata partendo da una strategia per i contenuti, che si basa sugli obiettivi commerciali per definire gli obiettivi della documentazione. La strategia per i contenuti viene quindi utilizzata per creare un IA, che definisce il layout e la struttura della documentazione. Da qui, è possibile scegliere le toolchain e scrivere i contenuti. La realtà della maggior parte dei progetti open source è che la strategia per i contenuti è semplice: "scrivi della documentazione in modo che le persone sappiano come utilizzare questo progetto", ma anche questa semplice strategia è sufficiente per poter definire un'IA efficace.
Lo scopo di questa guida è fornire uno strumento semplificato per consentire agli autori non professionisti di sviluppare un'IA sufficiente per determinare quali modelli utilizzare. Deve essere abbastanza semplice da essere completato da una persona normale in un pomeriggio e deve favorire l'azione rispetto all'istruzione. Idealmente, introdurrà i concetti in modo conciso, indirizzerà il lettore a considerare questi concetti in relazione al proprio progetto e utilizzerà il risultato per passare al concetto successivo.
Come struttura di base per questo progetto, sono necessari alcuni aggiornamenti al file README del progetto, in modo che i lettori comprendano come iniziare a utilizzare il progetto Good Docs e possano utilizzare efficacemente la guida sull'IA per scegliere i modelli.
Segmento di pubblico principale
Tutte le persone che vogliono utilizzare i modelli di The Good Docs Project per creare la documentazione del proprio progetto
Casi d'uso: Questa sezione è progettata per esplorare il modo in cui i lettori approcciano la Guida all'IA. Questo può aiutarci a identificare come deve essere strutturata la guida per servire al meglio questi lettori.
Scenario:
una persona sta lavorando a un progetto open source con poca o nessuna documentazione o a una suite di documentazione organizzata o scritta male. Decide di utilizzare il progetto Good Docs per organizzare la documentazione, ma non sa da dove iniziare. Seguono il file README per capire come iniziare a utilizzare i modelli e Information Architecture Guide per sviluppare la loro strategia per i contenuti e pianificare l'aspetto della suite di documentazione.
Proposta
Aggiorna il file README per guidare in modo più chiaro il nuovo lettore attraverso il progetto, inclusi i primi passaggi chiari. Uno dei primi passaggi consiste nel leggere e rispondere alle domande di una nuova guida sull'IA. Questa guida invita il lettore a prendere in considerazione il pubblico, lo schema dei contenuti, le matrici utente/attività e così via, senza gravare troppo sul lettore per imparare/comprendere cosa sono queste cose in senso accademico. Al termine di questa attività, il lettore avrà compreso quali modelli sono richiesti e come completarli al meglio.
Research
Per avvalorare questa affermazione con ricerche, mi affiderei molto al libro di Abby Covert (http://www.howtomakesenseofanymess.com/), in parte perché lo conosco molto bene e ha costituito la base di molti contenuti che ho già scritto e che utilizzerò, ma anche perché è molto facile da leggere per chi è alle prime armi con l'IA. In questo senso, è un po' una droga di passaggio per l'IA.
Bozza TOC
LEGGIMI:
-- Introduzione al progetto Good Docs |_ Chi deve utilizzare i modelli |_ Come funzionano i modelli |_ Contribuire al progetto -- I modelli |_ Elenco di tutti i modelli attuali |_ Scegliere i modelli da utilizzare |_ Prima di iniziare -- Prima di iniziare a scrivere |_ Chi legge i documenti? |_ Perché leggono la documentazione? |_ Scrivere per i lettori
Guida all'IA:
-- Introduzione |_ Che cos'è l'IA? |_ Perché dovrebbe interessarmi? -- Identifica il disordine - Esprimi il tuo intento - Affronta la realtà -- Scegli una direzione -- Misura la distanza -- Gioca con la struttura -- Preparati ad adattarti