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:
- Tor Project
- Pisarz techniczny:
- Swati Thacker
- Nazwa projektu:
- Przepisywanie strony Tor w przewodniku
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
Po rozmowie z mentorami TOR, aby poznać ich oczekiwania wobec tego projektu, proponuję te pomysły, które mają na celu ustanowienie spójnej struktury i formatu strony podręcznika TOR (https://2019.www.torproject.org/docs/tor-manual.html.en), aby uczynić ją przydatnym, szybkim źródłem informacji dla użytkowników. Ten projekt zakończy się w ciągu 3 miesięcy. Poniższe pomysły są podzielone według miesięcy.
Miesiąc 1:
Utwórz spis treści dla tej strony. Spis treści będzie zawierać temat ogólny oraz nagłówki wszystkich 9 kategorii opcji konfiguracji. Do końca tego miesiąca użytkownicy będą mieli dostęp do różnych kategorii konfiguracji. Spis treści będzie wyglądał tak:
- Omówienie – dodaj informacje o tym, gdzie TOR przechowuje konfigurację dla różnych kategorii opcji (czy są one w jednym miejscu), nazwę i domyślną lokalizację pliku konfiguracji, reguły używania opcji poleceń oraz sposób modyfikowania tych opcji przez użytkowników. (Informacje z tekstu wprowadzającego można umieścić w temacie FORMAT PLIKU KONFIGURACJI).
- Opcje ogólne
- Opcje klienta
- Opcje serwera
- Opcje serwera katalogowego
- Testowanie opcji sieciowych
- Opcje zapobiegania atakom typu DoS
- Opcje serwera urzędu katalogowego
- Ukryte opcje usługi
- Opcje nietrwałe
Miesiąc 2:
Celem strony z instrukcjami musi być szybkie udzielenie odpowiedzi na pytania o to, co robi każda opcja i w jaki sposób. Obecnie opcje nie są udokumentowane w uporządkowanym formacie, a informacje o każdej z nich są podane w akapitach, co utrudnia ich szybkie znalezienie. Wszystkie istniejące informacje o opcjach należy uporządkować za pomocą szablonu. Do końca tego miesiąca będziemy mieć spójny format dokumentacji dotychczasowych opcji i wszystkich nowych opcji w przyszłości. Dodatkowo ten format ułatwi w przyszłości korzystanie z podręcznika TOR jako strony „man”.
- Najpierw dodaj krótki opis każdej kategorii opcji, np. Opcje serwera, Opcje klienta itd. Dzięki nim użytkownicy będą wiedzieć, czego mogą się spodziewać w poszczególnych kategoriach.
- Utwórz szablon, aby zdefiniować spójny format dokumentowania poszczególnych opcji. Proponuję uwzględnienie w szablonie tych sekcji i pod-sekcji.
- Nazwa: nazwa opcji, która jest udokumentowana. Przykład: BandwidthBurst
- Synopsys: podsumowanie składni opcji w wierszu poleceń. Przykład: BandwidthBurst N bajtów
- Opis: opisz, do czego służy opcja konfiguracji i jaka jest jej wartość domyślna. Przykład: użyj tej opcji, aby ograniczyć maksymalny rozmiar puli tokenów (busrt) do podanej liczby bajtów w każdym kierunku. Domyślnie jest to 1 GB.
- Wartość opcji: wymień i opisz wartości dozwolone przez opcję. Szczegółowo opisz, do czego służy każda wartość i jak użytkownik powinien ją wpisać.
Miesiąc 3:
Obecnie istnieje 9 grup/kategorii opcji konfiguracji. Aby ułatwić wyszukiwanie i ułatwić sobie wyszukiwanie, utwórz stronę indeksu z listą opcji konfiguracji posortowanych alfabetycznie w ramach każdej z 9 kategorii. Te kategorie można następnie uporządkować według ich priorytetu, umieszczając na górze najczęściej używane kategorie opcji.
Po upływie 3 miesięcy możemy udostępnić zaktualizowaną wersję podręcznika TOR, który może służyć użytkownikom jako szybka pomoc w modyfikowaniu ustawień konfiguracji w TOR.