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
- ScummVM
- Specjalista ds. technicznych:
- Cadi
- Nazwa projektu:
- Uruchomienie portalu dokumentacji
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Cele:
- Opracowanie wysokiej jakości, wersjonowanej dokumentacji dla użytkowników przez konsolidację dużych ilości informacji z różnych źródeł i ich modyfikację w celu zapewnienia ich przejrzystości, spójności i kompletności.
- Dokumentacja powinna być zrozumiała dla początkujących, ale nie powinna być protekcjonalna w stosunku do zaawansowanych użytkowników.
- Aby utworzyć portal dokumentacji za pomocą generatora witryn statycznych.
- Aby dokumentacja dla użytkowników była gotowa na przyszłość, należy utworzyć szablony i szczegółowe instrukcje dla przyszłych autorów kodu open source.
Obecna sytuacja:
- Dokumentacja ScummVM jest dostępna w różnych źródłach.
- Informacje są trudne do znalezienia i często powielane; łatwo się zgubić na niejasnych stronach.
- Trudno jest określić, które informacje są aktualne, a które nie.
- Brakuje niektórych informacji lub są one niekompletne.
Rozwiązywanie problemu:
Sugerowana struktura dokumentacji:
Strona docelowa
|-- Pierwsze kroki
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (platforma)
|-- Korzystanie z ScummVM
| |-- Uruchomienie
| |-- Ustawienia globalne
| |-- Ustawienia gry
| -- Keyboard shortcuts
|-- Advanced options
| |-- Cloud and LAN
| |-- Control Mapping
| |-- Configuration
| |-- Command line options
| |-- Graphics
|-- Muzyka i dźwięk
|-- Pomoc
| |-- Najczęstsze pytania
| |-- Kontakt
| |-- Znane problemy
| -- Reporting a bug
|-- Game Notes-- Informacje o wersji
- Pierwsze kroki:
Nowi użytkownicy często szukają krótkiego przewodnika, aby jak najszybciej rozpocząć pracę. Chociaż instalacja ScummVM może być skomplikowana na niektórych platformach, zainstalowanie go na komputerze nie jest trudne.
Przewodnik dla początkujących powinien zawierać te informacje:
- Jak zainstalować ScummVM na komputerach z systemem Windows, Mac i Linux.
Jak wczytywać, dodawać i uruchamiać gry.
Instalowanie ScummVM:
W przypadku, gdy instalacja nie jest intuicyjna lub użytkownik nie ma dużej wiedzy technicznej, potrzebuje on obszernego przewodnika po instalacji ScummVM na dowolnej z obsługiwanych platform.
Każda strona z pełną instrukcją instalacji powinna zawierać te informacje:
- Wszelkie wymagania systemowe i wymagania wstępne.
- Jak pobrać odpowiednią wersję ScummVM.
- Jak zainstalować ScummVM
- jak wczytywać gry na wybranej platformie, zwłaszcza gdy nie jest to platforma, na którą została ona zaprojektowana;
Jak uruchomić ScummVM, dodać grę i uruchomić grę.
Przy użyciu ScummVM:
Użytkownicy potrzebują dokumentów referencyjnych, które wyjaśniają, jak korzystać z ScummVM.
Dokumenty odniesienia powinny zawierać te informacje:
- Interfejs Launchera z wyglądem każdego okna i karty oraz sposobem ich działania.
- Objaśnienie dostępnych ustawień globalnych i ustawień dotyczących konkretnej gry.
Skróty klawiszowe/klawisze skrótów.
Opcje zaawansowane:
Zaawansowani użytkownicy potrzebują dodatkowych, bardziej technicznych informacji o dostępnych opcjach dostosowywania działania gier.
- Uwagi dotyczące gry:
wszelkie informacje dotyczące gry, które użytkownik musi znać, w tym między innymi: - dziwactwa instalacji - wymagane dodatkowe pliki - nietypowe lub inne elementy sterujące
- Znane problemy:
Powinna ona zawierać wszystkie znane błędy występujące w danej wersji.
- Informacje o wersji:
Nasza dokumentacja będzie wersjonowana, ale sekcja z informacjami o wersji może być przydatna do podsumowania zmian w najnowszej wersji. Mogą to być obszary, które obecnie wykraczają poza zakres tej dokumentacji, takie jak nowo obsługiwane gry lub informacje o nowych silnikach.
Plan ataku:
Proponuję zacząć od utworzenia szablonu stron Instalowanie ScummVM, ponieważ będzie to najłatwiejszy sposób na uzyskanie wymaganych informacji od administratorów/programistów portu (szczególnie w przypadku, gdy te informacje są skąpe lub nieistniejące). Wstępnie uzupełnię wszystkie informacje, które mam już w dokumentacji, które można następnie sprawdzić pod kątem kompletności, dokładności i waluty lub dodać je w razie potrzeby.
Następnie przejdę istniejącą dokumentację: README, wiki i witrynę. W miarę potrzeby będę zmieniać i uzupełniać poszczególne sekcje oraz przenosić wszystkie informacje do nowego portalu. Zanotuję też, skąd pochodzą pobierane informacje, aby mieć pewność, że po opublikowaniu portalu nie będzie zawierał podwójnych wpisów, sprzecznych informacji ani innych nieprawidłowości.
W tym celu będę współpracować z mentorami, deweloperami, osobami zajmującymi się portami i innymi ekspertami w danym temacie, aby uzyskać brakujące informacje, a także dbać o to, aby każda strona była jak najbardziej aktualna i pełna.
W duchu współpracy i za zgodą mentorów chciałbym udostępnić portal z pracami w toku społeczności ScummVM na czas pisania, aby otrzymywać opinie w czasie rzeczywistym i mieć pewność, że nic nie zostanie pominięte.
Zalecamy korzystanie z poradnika dotyczącego stylu, np. poradnika dotyczącego stylu w dokumentacji dla deweloperów Google, aby zapewnić spójność tej pracy i wszystkich przyszłych dokumentów.
W miarę możliwości używam zrzutów ekranu, GIF-ów i innych pomocy wizualnych, aby ułatwić zrozumienie.
Proponowany harmonogram:
Budowanie społeczności 17 sierpnia – 13 września 2020 r.
Kontynuuj rozmowy z mentorami i szerszą społecznością ScummVM, aby dopracować wizję projektu i sfinalizować szczegóły, takie jak struktura i zawartość dokumentów.
Tydzień 1 14–20 września
- Utwórz szablon dla stron instalacji na poszczególnych platformach.
- Wstępnie wypełnij szablony za pomocą istniejących informacji i prześlij je do odpowiednich deweloperów lub osób odpowiedzialnych za portowanie, aby uzyskać więcej informacji.
Tydzień 2 21–27 września
- Skonfiguruj nowy portal dokumentacji.
Tydzień 3 28 września – 4 października
Korzystanie z ScrumVM: - Interfejs - Ustawienia globalne Instalowanie ScrumVM: - Przewodniki instalacyjne dla poszczególnych platform, gdy gotowe szablony są do mnie zwracane.
Tydzień 4 5–11 października
Korzystanie z ScrumVM: - Ustawienia gry - Skróty klawiszowe Instalowanie ScrumVM: - Przewodniki instalacyjne dla poszczególnych platform, gdy wypełnione szablony są do mnie zwracane
Tydzień 5 12–18 października
Opcje zaawansowane: - Cloud i LAN - Mapowanie sterowania Instalowanie ScummVM: - Przewodniki instalacji dla poszczególnych platform, gdy gotowe szablony są do mnie zwracane
Tydzień 6 19–25 października
Opcje zaawansowane: - Konfiguracja - Opcje wiersza poleceń Instalowanie ScummVM: - Przewodniki instalacji dla poszczególnych platform, gdy gotowe szablony są zwracane do mnie
Tydzień 7 26 października–1 listopada
Opcje zaawansowane: - Grafika - Dźwięk Instalowanie ScummVM: - Przewodniki instalacji dla poszczególnych platform, gdy gotowe szablony są do mnie zwracane
Tydzień 8 2–8 listopada
Pomoc: - Najczęstsze pytania - Kontakt - Znane problemy
Instalowanie ScummVM: - Przewodniki instalacyjne dla poszczególnych platform, gdy zwracane są ukończone szablony
Tydzień 9 9–15 listopada
Pomoc: - zgłaszanie błędu - informacje o grze - informacje o wersji
Instalowanie ScummVM: - Dokończ wszystkie przewodniki po platformach, które nie zostały jeszcze ukończone.
Tydzień 10 16–22 listopada
- ostateczna edycja, korekta i dopracowywanie decyzji dotyczących portalu, takich jak nawigacja na pasku bocznym, ustawienia motywu lub CSS itp.
- Upewnij się, że wszystkie linki działają zgodnie z oczekiwaniami.
- Sprawdź, czy obrazy i gify wyświetlają się prawidłowo.
Tydzień 11 23–30 listopada
- Zakończ wszystkie nieukończone zadania i oficjalnie uruchom portal.
- Po uruchomieniu portalu usuń zbędne informacje z innych źródeł w porozumieniu z mentorem.