Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- HPX
- Pisarz techniczny:
- rstobaugh
- Nazwa projektu:
- Edytowanie i upraszczanie dokumentacji HPX
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Moją propozycją jest zredagowanie i usprawnienie treści obecnej dokumentacji HPX. Moja propozycja dotyczy standardowego (trzymiesięcznego) projektu, który koncentruje się na przeredagowaniu dwóch rozdziałów podręcznika organizacji STE||AR: „System kompilacji i uruchamianie HPX” (1) oraz „Konfigurowanie aplikacji HPX” (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”. Poza tym zawiera on powtarzające się informacje, których planuję zmienić odpowiednio do potrzeb, ujednolicić i przyciąć. Rozdział o konfigurowaniu aplikacji HPX również zawiera kilka błędów gramatycznych, które trzeba poprawić, ale najważniejszą obawą w tym rozdziałie jest jego przydatność dla użytkownika. W tym rozdziałie chcę poruszyć 3 główne problemy projektowe:
Niektóre nagłówki są ukryte w tekście, co utrudnia przeglądanie rozdziału. Obecnie użytkownik musi uważnie przeczytać instrukcję, aby zrozumieć przeznaczenie poszczególnych tabel. Nie dzieje się tak w przypadku większości użytkowników, którzy korzystają z instrukcji, zwłaszcza jeśli przeczytali ją już wcześniej. Zależy mi na tym, by każda tabela miała wyraźny, wyraźny nagłówek, który będzie dobrze widoczny dla użytkowników przewijających tekst.
Gdy w ramach określonego nagłówka wyświetlają się różne właściwości, ich kolejność nie jest logiczna. Chociaż właściwości są pogrupowane według wspólnego motywu, nie ma żadnej podgrupy, przez co informacje są rozproszone. Użytkownik może np. mieć do czynienia z kilkoma witrynami o charakterze lokalnym, z których kilka dotyczy innego tematu, i drugiej o lokalizacji. Ze względu na brak struktury wewnętrznej pod nagłówkami trudniej jest znaleźć wszystkie informacje dotyczące danego podtematu. W związku z tym zamierzam uporządkować kilka wykresów, aby lepiej zgrupować podobne informacje pod każdym nagłówkiem.
Użytkownicy muszą przechodzić wstecz i z powrotem między sekcjami (lub otwierać instrukcję w 2 osobnych kartach), aby w pełni zrozumieć określone instrukcje. W niektórych momentach rozdział kieruje użytkownika do jednego zdania z poprzedniej sekcji w sposób, który zmusza użytkownika do przewinięcia w górę lub do przejścia po hiperlinku, który pozwala zapoznać się z dokładnymi instrukcjami. Instrukcja używa niejasnego języka, np. „ten krok jest wykonany po kroku 11” w poprzedniej sekcji. Chociaż ta metoda eliminuje powtarzanie, utrudnia zrozumienie instrukcji, ponieważ należy wykonać te zadania w określonej kolejności. Zamiast tego proponujemy użycie bardziej szczegółowych sformułowań, aby użytkownicy nie musieli przerywać procesu czytania poprzez przełączanie się między sekcjami lub dokumentami.
Jeśli wypełnię te sekcje przed zakończeniem standardowego harmonogramu, zechcę wyczyścić stronę „Why HPX?” (3) w dokumentacji użytkownika grupy STE||AR. Ta strona zawiera powtarzalne wprowadzenie, które mam nadzieję skonsolidować, i zawiera niespójności w pisowni (szczególnie w żargonie) i w tonie, przez co jest niespójna. Moim celem jest stworzenie bardziej ujednoliconego i spójnego wprowadzenia do pracy grupy STE||AR.