Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- TheGoodDocsProject
- Technical writer:
- Località
- Nome progetto:
- Guida all'architettura delle informazioni
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Piano guida all'architettura delle informazioni
Questo documento illustra la pianificazione di una guida all'architettura delle informazioni per il progetto Good Docs. È stato preparato nell'ambito di un invio per la stagione dei documenti Google 2020. Descrive il caso d'uso per la guida proposta e disegna un piano della struttura di tale guida a scopo di pianificazione.
L'architettura dell'informazione (IA) riguarda il modo in cui sono organizzati i contenuti. Copre la struttura dei contenuti senza definire lo stile o le parole utilizzate all'interno dei contenuti stessi. Ad esempio, un piano di IA considera chi è il lettore, il suo approccio ai contenuti e l'ambiente in cui sta leggendo. Dovrebbe quindi prendere in considerazione una struttura adeguata dei contenuti che soddisfi al meglio i requisiti dei lettori.
In un mondo perfetto, la documentazione è progettata partendo da una strategia per i contenuti, che utilizza gli obiettivi aziendali per definire gli obiettivi della documentazione. La strategia per i contenuti viene quindi utilizzata per creare un IA che definisca 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 come "scrivere una documentazione in modo che le persone sappiano come utilizzare il progetto", ma anche questa semplice strategia è sufficiente per essere in grado di definire un IA efficace.
Lo scopo di questa guida è fornire uno strumento semplificato agli autori non professionisti per sviluppare un IA che sia sufficiente per determinare i modelli da utilizzare. Dovrebbe essere abbastanza semplice da essere completata da un normale essere umano in un pomeriggio e dovrebbe favorire l'azione piuttosto che l'istruzione. Idealmente, introdurrà i concetti in modo conciso, guiderà il lettore a considerare questi concetti in relazione al proprio progetto e ne userà il risultato per passare al concetto successivo.
Sono necessari alcuni aggiornamenti al file README del progetto come struttura di sostegno per questo progetto, in modo che i lettori capiscano come iniziare a utilizzare il progetto Good Docs e siano in grado di utilizzare efficacemente la guida IA per guidare le scelte dei modelli.
Pubblico principale
Tutte le persone che vogliono utilizzare i modelli del progetto The Good Docs per creare documentazione per il proprio progetto
Casi d'uso: Questa sezione è progettata per esplorare il modo in cui i lettori si avvicinano alla Guida IA. Questo può aiutarci a capire come strutturare la guida per servire al meglio questi lettori.
Scenario:
una persona sta lavorando a un progetto open source con documentazione scarsa o nulla o una suite di documentazione mal organizzata o scritta. Decide di utilizzare The Good Docs Project per organizzare la propria documentazione, ma non sa da dove iniziare. Seguono il README per capire come iniziare a utilizzare i modelli e seguono il Information Architecture Guide per sviluppare la propria strategia per i contenuti e pianificare l'aspetto della suite di documentazione.
Proposta
Aggiorna il README per guidare in modo più chiaro il nuovo lettore attraverso il progetto, inclusi primi passaggi chiari. Uno di questi primi passaggi consiste nel leggere e rispondere alle domande in una nuova Guida di IA. Questa guida inviterebbe il lettore a prendere in considerazione il pubblico, lo schema dei contenuti, le matrici di utenti/attività e così via, senza gravare troppo sul lettore per imparare/comprendere quali sono queste cose in senso accademico. Una volta completata questa attività, il lettore ha capito quali modelli sono necessari e come completarli al meglio.
Ricerca
A sostegno di questa ricerca, mi soffermerei molto sul 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 di cui utilizzerò, ma anche perché è molto facile per le persone che non hanno esperienza in IA acquisire e leggere ulteriormente se hanno È un farmaco gateway IA, in questo senso.
Riepilogo bozza
LEGGIMI:
-- Introduzione al progetto Good Docs |_ Chi dovrebbe utilizzare i modelli |_ Come funzionano i modelli |_ Contributo al progetto -- I modelli |_ Elenco di tutti i modelli attuali |_ Scelta dei modelli da utilizzare |_ Prima di iniziare -- Prima di iniziare a scrivere |_ Chi legge i documenti? |_ Perché leggono i documenti? |_ Scrivere per i tuoi lettori
Guida per IA:
-- Introduzione |_ Che cos'è l'IA? |_ Perché dovrebbe interessarmi? -- Identifica il caos -- Dichiara le tue intenzioni -- Fatti notare dalla realtà -- Scegli una direzione -- Misura la distanza -- Gioca con la struttura -- Preparati per l'adattamento