Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- ScummVM
- Pisarz techniczny:
- Cadi
- Nazwa projektu:
- Uruchom portal dokumentacji
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Cele:
- Aby stworzyć wysokiej jakości, wersjonowaną dokumentację dla użytkowników przez konsolidację dużych ilości informacji z różnych źródeł i przeredagowanie informacji w celu ich przejrzystości, spójności i kompletności.
- Dokumentacja powinna być łatwa do zrozumienia dla początkujących użytkowników i nie będzie potraktowana jako protekcjonalna dla użytkowników obeznanych z technologią.
- Tworzenie portalu z dokumentacją za pomocą generatora witryn statycznych
- z myślą o przygotowaniu dokumentacji użytkowników na przyszłość, tworząc szablony i szczegółowe instrukcje dla przyszłych współtwórców oprogramowania open source.
Obecna sytuacja:
- Dostępna dokumentacja ScummVM jest rozproszona w wielu źródłach.
- Informacje są trudne do znalezienia i często są duplikowane, więc łatwo jest zgubić się na ciemnej stronie.
- Trudno powiedzieć, które informacje są aktualne, a które nieaktualne.
- Brakuje niektórych informacji lub są one niepełne.
Jak rozwiązać problem:
Sugerowana struktura dokumentacji:
Strona docelowa
|-- Pierwsze kroki
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (platforma)
|-- Korzystanie ze ScummVM
| |-- Menu z aplikacjami
| |-- Ustawienia globalne
| |-- Ustawienia gry
| -- Keyboard shortcuts
|-- Advanced options
| |-- Cloud and LAN
| |-- Control Mapping
| |-- Configuration
| |-- Command line options
| |-- Graphics
| – Muzyka i dźwięk
|-- Pomoc
| |-- FAQ
| |-- Kontakty
| |-- Znane problemy
| -- Reporting a bug
|-- Game Notes-- Informacje o wersji
- Pierwsze kroki:
Nowi użytkownicy często szukają krótkiego przewodnika dla początkujących, który pozwoli im jak najszybciej rozpocząć pracę. Instalacja ScummVM na niektórych platformach może być skomplikowana, ale instalacja na komputerze już nie.
Krótki przewodnik powinien obejmować następujące zagadnienia:
- Jak zainstalować ScummVM w systemach Windows, macOS i Linux.
Jak wczytać, dodać i uruchomić grę.
Instalowanie ScummVM:
Jeśli instalacja nie jest intuicyjna lub użytkownik może nie mieć wystarczającej bazy technicznej, powinien otrzymać kompleksowy przewodnik na temat instalowania ScummVM na dowolnej z obsługiwanych platform.
Każda kompleksowa strona instalacji powinna obejmować następujące informacje:
- Wszystkie wymagania systemowe i wymagania wstępne.
- Jak pobrać odpowiednią wersję ScummVM.
- Jak zainstalować ScummVM.
- Jak wczytywać gry na wybranej platformie, zwłaszcza jeśli nie jest to platforma, na którą gra została zaprojektowana.
Jak uruchomić ScummVM, dodać grę i ją uruchomić.
Korzystanie ze ScummVM:
Użytkownicy potrzebują dokumentów referencyjnych, które wyjaśniają, jak używać ScummVM.
Dokumenty referencyjne powinny obejmować następujące informacje:
- Interfejs Menu z aplikacjami; wygląd poszczególnych okien i kart oraz sposób ich działania.
- Wyjaśnienie dostępnych ustawień – globalnych i powiązanych z grami.
Skróty klawiszowe/skróty klawiszowe.
Opcje zaawansowane:
Zaawansowani użytkownicy potrzebują dodatkowych, bardziej technicznych informacji o dostępnych opcjach, które pozwolą im dostosować działanie gry.
- Notatki do gry:
Wszelkie informacje o grze, które musi znać użytkownik, w tym: – nietypowe czynności związane z instalacją, – wymagane dodatkowe pliki, – nietypowe lub inne elementy sterujące.
- Znane problemy:
Ta sekcja powinna zawierać wszelkie znane błędy występujące w danej wersji.
- Informacje o wersji:
Nasza dokumentacja będzie stale uaktualniana, ale warto dodać sekcję Informacje o wersji, w której znajdziesz podsumowanie zmian w najnowszej wersji. Może to dotyczyć obszarów, które obecnie nie są uwzględnione w tej dokumentacji, np. nowo obsługiwanych gier czy informacji o nowych wyszukiwarkach.
Plan ataku:
Proponuję zacząć od utworzenia szablonu dla stron Instalowanie ScummVM, ponieważ będzie to dla mnie najprostszy sposób na uzyskanie potrzebnych informacji od właścicieli/programistów portów (zwłaszcza tam, gdzie jest ich niewiele lub nie ma ich wcale). Wstępnie uzupełnię wszystkie informacje, które posiadam w dotychczasowej dokumentacji, i będzie można je sprawdzić pod kątem ich kompletności, dokładności i waluty lub w razie potrzeby dodać nowe.
Następnie przejdę istniejącą dokumentację: README, wiki i witrynę. Będę pisać od nowa i w razie potrzeby dodawać kolejne sekcje do poszczególnych sekcji i pobierać wszystkie informacje do nowego portalu. Będę zaznaczać też, skąd pochodzą informacje, aby mieć pewność, że po uruchomieniu portalu nie ma podwójnej presji, sprzeczności ani innych anomalii.
Przez cały czas będę współpracować z mentorami, programistami, opiekunami portów i innymi ekspertami z danej dziedziny, aby pozyskiwać brakujące informacje i dbać o to, aby każda strona była jak najbardziej aktualna i wyczerpująca.
Zgodnie z duchem współpracy i po uzyskaniu zgody od mentorów chcę zapewnić społeczności ScummVM dostęp do portalu prac w trakcie pisania, aby otrzymywać opinie w czasie rzeczywistym i mieć pewność, że nic nie umknie Twojej uwadze.
Aby zapewnić spójność tych materiałów i całej dokumentacji, sugeruję skorzystanie z przewodnika stylistycznego, takiego jak przewodnik po stylu dokumentacji Google dla deweloperów.
W miarę możliwości będę wykorzystywać zrzuty ekranu, GIF-y i inne pomoce wizualne, aby pogłębić zrozumienie.
Proponowany harmonogram:
Więź ze społecznością 17 sierpnia–13 września 2020 r.
Poświęć trochę czasu na rozmowy z mentorami i szerszą społecznością ScummVM, aby dopracować wizję projektu i sfinalizować szczegóły, takie jak struktura i treści dokumentu.
Tydzień 1 14 września–20 września
- Utwórz szablon stron instalacji na odpowiedniej platformie.
- Wstępnie wypełnij szablony wszelkimi istniejącymi informacjami i przekaż je odpowiednim podmiotom/deweloperom w celu uzyskania dodatkowych informacji.
Tydzień 2 21 września–27 września
- Skonfiguruj nowy portal z dokumentacją.
Tydzień 3 28 września–4 października
Korzystanie ze ScummVM: – interfejs, – ustawienia globalne, instalowanie ScummVM: – przewodniki instalacji dotyczące konkretnej platformy, gdy do mnie trafiają gotowe szablony.
Tydzień 4 5 października–11 października
Korzystanie ze ScummVM: – ustawienia gry, – skróty klawiszowe, instalowanie ScummVM: – instrukcje instalacji dotyczące konkretnej platformy, gdy otrzymam gotowe szablony.
Tydzień 5 12–18 października
Opcje zaawansowane: – Chmura i sieć LAN – Mapowanie sterowania Instalowanie ScummVM: – Przewodniki instalacji dotyczące konkretnej platformy, gdy są zwracane gotowe szablony.
Tydzień 6 19–25 października
Opcje zaawansowane: – konfiguracja, – opcje wiersza poleceń, instalowanie ScummVM: – przewodniki instalacji dotyczące konkretnej platformy, gdy są zwracane gotowe szablony.
Tydzień 7 26 października–1 listopada
Opcje zaawansowane: – grafika, – dźwięk, instalowanie ScummVM: – przewodniki instalacji dotyczące konkretnej platformy, gdy otrzymam gotowe szablony.
Tydzień 8 2 listopada–8 listopada
Pomoc: – Najczęstsze pytania – Kontakty – Znane problemy
Instalowanie ScummVM: – przewodniki instalacji dotyczące poszczególnych platform, w których pojawiają się gotowe szablony,
Tydzień 9 9 listopada–15 listopada
Pomoc: – Zgłaszanie błędu, – Informacje o grze, – Informacje o wersji.
Instalowanie ScummVM: – Sfinalizuj wszystkie przewodniki dotyczące platformy, które nie zostały jeszcze ukończone.
Tydzień 10 16–22 listopada
- Końcowa edycja, korekta i finalizacja wszelkich decyzji związanych z portalem, takich jak nawigacja na pasku bocznym, zmiany motywu, CSS itp.
- Sprawdź, czy wszystkie linki działają zgodnie z oczekiwaniami.
- Sprawdź, czy obrazy i GIF-y wyświetlają się prawidłowo.
Tydzień 11 23 listopada–30 listopada
- Sfinalizuj wszystkie oczekujące przedmioty i oficjalnie uruchom portal!
- Po uruchomieniu portalu usuń zbędne informacje z innych źródeł, zasięgając opinii mentorów.