Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- HPX
- Pisarz techniczny:
- rstobaugh
- Nazwa projektu:
- Edytowanie i upraszczanie istniejącej dokumentacji HPX
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Proponuję zmodyfikowanie i uproszczenie treści istniejącej dokumentacji HPX. Proponuję projekt o standardowej długości (3 miesiące), który skupia się na poprawie 2 rozdziałów podręcznika grupy STE||AR: „HPX Build System and Launching” (1) oraz „Configuring HPX Applications” (2).
Rozdział „System kompilacji i uruchamianie HPX” zawiera kilka błędów gramatycznych, a także niejasny język i niespójne użycie wielkich liter w terminach, takich jak „CMake”. Zawiera on też powtarzające się informacje, które planuję zmienić, skonsolidować i przyciąć w razie potrzeby. Rozdział „Konfigurowanie aplikacji HPX” zawiera kilka błędów gramatycznych, które należy poprawić, ale moim głównym celem jest zapewnienie łatwości obsługi tego rozdziału. W tym rozdziale są 3 główne problemy z projektowaniem, które zamierzam rozwiązać:
Niektóre nagłówki są ukryte w tekście, przez co trudno jest przejrzeć rozdział. Obecnie użytkownik musi dokładnie przeczytać instrukcję, aby zrozumieć przeznaczenie każdej tabeli. Większość użytkowników nie korzysta z instrukcji obsługi w taki sposób, zwłaszcza jeśli czytali już wcześniej te treści. Zamiast tego planuję zadbać o to, aby każda tabela miała wyraźny nagłówek, który będzie łatwo widoczny, gdy użytkownik przewinie tekst.
Gdy wyświetlasz różne właściwości w ramach określonego nagłówka, nie są one uporządkowane w logicznej kolejności. Chociaż usługi są grupowane według wspólnego tematu, nie ma żadnych podgrup, co powoduje, że informacje są rozproszone. Użytkownik może na przykład napotkać kilka usług związanych z lokalizacją, kilka usług dotyczących innego tematu, a potem jeszcze inną usługę związaną z lokalizacją. Ten brak wewnętrznej struktury w ramach nagłówków utrudnia znalezienie wszystkich informacji na dany podtemat. Dlatego planuję zmienić układ kilku wykresów, aby wyraźniej grupować podobne informacje pod poszczególnymi nagłówkami.
Aby w pełni zrozumieć niektóre instrukcje, użytkownicy muszą przełączać się między sekcjami (lub otwierać instrukcję w 2 oddzielnych kartach). W pewnych miejscach rozdział kieruje użytkownika do pojedynczego zdania w poprzedniej sekcji w taki sposób, że zmusza czytelnika do przewinięcia w górę lub kliknięcia hiperłącza, aby zrozumieć dokładne instrukcje. W poprzedniej sekcji instrukcje są bowiem niejasne, np. „ten krok wykonuje się po kroku 11”. Ta metoda eliminuje powtórzenia, ale utrudnia zrozumienie instrukcji, ponieważ zadania te należy wykonać w określonej kolejności. Proponuję za to użycie bardziej szczegółowego sformułowania, aby użytkownicy nie musieli przerywać czytania przez przełączanie się między sekcjami lub dokumentami.
Jeśli uda mi się wypełnić te sekcje przed upływem standardowego terminu, chciałbym też uporządkować stronę „Dlaczego HPX?” (3) w ramach dokumentacji użytkownika grupy STE||AR. Ta strona zawiera powtarzające się treści wprowadzające, które mam zamiar scalić. Zawiera też niespójności w wielkich literach (zwłaszcza w żargonie) i sposobie wyrażania się, co sprawia, że całość wydaje się niespójnym. Moim celem jest stworzenie bardziej ujednoliconego i spójnego wprowadzenia do pracy grupy STE||AR.