Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- HPX
- Technical writer:
- rstobaugh
- Nome progetto:
- Modifica e semplifica la documentazione esistente di HPX
- Durata del progetto:
- Durata standard (3 mesi)
Project description
La mia proposta è modificare e semplificare il contenuto della documentazione HPX esistente. La mia proposta è per un progetto di durata standard (tre mesi) incentrato sulla revisione di due capitoli del manuale del gruppo STE||AR: ""Sistema di build HPX e lancio" (1) e "Configurazione di applicazioni HPX"" (2).
Il capitolo ""Sistema e lancio HPX Build"" contiene diversi errori grammaticali e contiene anche un linguaggio poco chiaro e lettere maiuscole incoerenti di termini come "CMake". Inoltre, contiene informazioni ripetute che ho intenzione di riorganizzare, consolidare e tagliare secondo necessità. Sebbene il capitolo sulla "Configurazione di applicazioni HPX" contenga anche alcuni errori grammaticali che devono essere risolti, la mia preoccupazione principale per questo capitolo è la sua facilità d'uso. Il capitolo tratta tre principali problemi di progettazione che intendo affrontare:
Alcune intestazioni sono nascoste all'interno del testo, il che rende difficile scorrere il capitolo. Attualmente, l'utente deve leggere attentamente il manuale per comprendere lo scopo di ogni tabella. La maggior parte degli utenti non interagisce con i manuali di istruzioni in questo modo, specialmente se hanno già letto i contenuti in precedenza. Prevedo piuttosto di assicurarmi che ogni tabella abbia un'intestazione chiara e distinta, che sia facilmente visibile se un utente scorre il testo.
Quando vengono elencate varie proprietà sotto un determinato titolo, le proprietà non seguono un ordine logico. Anche se le proprietà sono raggruppate insieme in base a un tema comune, non ci sono sottogruppi e le informazioni sembreranno sparse. Ad esempio, un utente potrebbe trovare diverse proprietà che si occupano della località, alcune relative a un altro argomento e un'altra che riguarda la località. Questa mancanza di struttura interna sotto le intestazioni rende difficile l'individuazione di tutte le informazioni su un argomento secondario specifico. Pertanto, ho intenzione di riorganizzare diversi grafici per raggruppare più chiaramente le informazioni simili sotto ogni intestazione.
Gli utenti sono costretti a spostarsi avanti e indietro tra le varie sezioni (o aprire il manuale in due schede separate) per comprendere appieno determinate istruzioni. Ci sono punti in cui il capitolo indirizza l'utente a una singola frase all'interno di una sezione precedente in modo da costringere il lettore a scorrere verso l'alto o a seguire un link ipertestuale per comprendere l'istruzione esatta, poiché il manuale utilizza un linguaggio vago come "questo passaggio viene eseguito dopo il passaggio 11" nella sezione precedente. Sebbene questo metodo elimini la ripetizione, rende più difficile comprendere le istruzioni, poiché si tratta di attività che devono essere eseguite in un ordine specifico. Propongo invece di includere un testo più specifico in modo che gli utenti non debbano interrompere il processo di lettura passando da una sezione all'altra o da un documento all'altro.
Se completo queste sezioni prima della fine della sequenza temporale standard, vorrei anche ripulire la pagina "Perché HPX?" (3) nella documentazione utente del gruppo STE||AR. Questa pagina contiene contenuti introduttivi ripetitivi, che spero di consolidare la situazione. Inoltre, presenta incongruenze in termini di lettere maiuscole (soprattutto in gergo) e tono, che gli conferiscono un aspetto disunificato. Il mio obiettivo sarebbe quello di creare un'introduzione più uniforme e coerente al lavoro del gruppo STE||AR.