Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione di Documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- HPX
- Redattore tecnico:
- rstobaugh
- Nome progetto:
- Modificare e semplificare la documentazione HPX esistente
- Durata del progetto:
- Durata standard (3 mesi)
Project description
La mia proposta è di modificare e semplificare i contenuti della documentazione HPX esistente. La mia proposta è un progetto con un termine standard (tre mesi) incentrato sulla revisione di due capitoli del manuale del gruppo STE||AR: ""HPX Build System and Launching"" (1) e ""Configuring HPX Applications"" (2).
Il capitolo ""HPX Build System and Launching"" contiene diversi errori grammaticali, nonché un linguaggio confuso e l'uso di lettere maiuscole incoerenti per termini come "CMake". Inoltre, contiene informazioni ripetute, che ho intenzione di riorganizzare, consolidare e rimuovere in base alle esigenze. Anche se il capitolo ""Configurazione delle applicazioni HPX"" contiene alcuni errori grammaticali che devono essere risolti, la mia preoccupazione principale per questo capitolo è la sua facilità d'uso. Questo capitolo presenta tre principali problemi di progettazione che ho intenzione di affrontare:
Alcune intestazioni sono nascoste all'interno del testo, il che rende difficile dare un'occhiata al capitolo. Attualmente, un 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, soprattutto se li ha già letti. Ho intenzione di assicurarmi che ogni tabella abbia un'intestazione chiara e distinta, che possa essere facilmente visualizzata se un utente scorre il testo.
Quando elenca varie proprietà sotto un'intestazione specifica, le proprietà non seguono un ordine logico. Sebbene le proprietà siano raggruppate in base a un tema comune, non sono presenti raggruppamenti secondari, il che rende le informazioni poco chiare. Ad esempio, un utente potrebbe trovare diverse proprietà che trattano la località, alcune che trattano un altro argomento e un'altra che tratta la località. Questa mancanza di struttura interna sotto le intestazioni rende più difficile trovare tutte le informazioni su un argomento secondario specifico. Pertanto, ho intenzione di riorganizzare diversi grafici per raggruppare in modo più chiaro le informazioni simili sotto ogni intestazione.
Gli utenti sono costretti a spostarsi avanti e indietro tra le sezioni (o ad aprire il manuale in due schede separate) per comprendere appieno determinate istruzioni. In alcuni punti del capitolo l'utente viene indirizzato a una singola frase all'interno di una sezione precedente in modo da costringerlo 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 le ripetizioni, rende più difficile comprendere le istruzioni, poiché si tratta di attività che devono essere eseguite in un ordine specifico. Propongo invece di includere formulazioni più specifiche 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 del termine della tempistica standard, vorrei anche riordinare la pagina "Perché HPX?" (3) nella documentazione utente del gruppo STE||AR. Questa pagina include contenuti introduttivi ripetitivi, che spero di consolidare, e contiene incongruenze nell'uso delle lettere maiuscole (soprattutto gergo) e nel tono, che conferiscono un'atmosfera unificata. Il mio obiettivo è creare un'introduzione più unificata e coerente al lavoro del gruppo STE||AR.