Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- ScummVM
- Pisarz techniczny:
- kadi
- 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 zapewnienia ich przejrzystości, spójności i kompletności.
- Dokumentacja powinna być zrozumiała dla początkujących, a jej treść nie powinna być czytelna dla użytkowników obeznanych z technologią.
- Aby utworzyć portal dokumentacji za pomocą generatora witryn statycznych.
- Dzięki szablonom i szczegółowym instrukcjom dla użytkowników, którzy będą chcieli w przyszłości wykorzystać zasoby open source,
Obecna sytuacja:
- Dostępna dokumentacja ScummVM jest rozproszona w różnych źródłach.
- Informacje są trudne do znalezienia i często powtarzane, dlatego łatwo zgubić się na niejasnych stronach.
- Trudno powiedzieć, które informacje są aktualne, a które nieaktualne.
- Brakuje niektórych informacji lub są one niepełne.
Jak naprawić 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
| |-- Często zadawane pytania
| |-- 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 może być skomplikowana na niektórych platformach, ale instalowanie jej na komputerze już nie.
Krótkie wprowadzenie powinno obejmować te zagadnienia:
- Jak zainstalować ScummVM w systemach Windows, Mac i Linux.
Jak wczytać, dodać i uruchomić grę.
Instalowanie ScummVM:
Jeśli instalacja nie jest intuicyjna lub użytkownik może nie mieć zaawansowanej wiedzy technicznej, potrzebny będzie 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.
- Sposób wczytywania gier na wybranej platformie, zwłaszcza na innej platformie, na którą została zaprojektowana.
Jak uruchomić ScummVM, dodać grę i uruchomić grę.
Korzystanie ze ScummVM:
Użytkownicy potrzebują dokumentów referencyjnych, które wyjaśniają, jak korzystać ze ScummVM.
Dokumenty referencyjne powinny obejmować:
- Interfejs Launchera; jak wyglądają poszczególne okna i karty oraz jak działają.
- Wyjaśnienie dostępnych ustawień, zarówno globalnych, jak i dotyczących konkretnych gier.
Skróty klawiszowe/klawisze skrótów.
Opcje zaawansowane:
Zaawansowani użytkownicy potrzebują dodatkowych, bardziej technicznych informacji o dostępnych opcjach dostosowywania sposobu działania gier.
- Notatki do gry:
Wszystkie informacje dotyczące gier, które musi znać użytkownik, w tym: – charakterystyczne elementy instalacji, – wymagane dodatkowe pliki, – nietypowe lub inne elementy sterujące.
- Znane problemy:
Ta sekcja powinna zawierać wszystkie znane błędy występujące w danej wersji.
- Informacje o wersji:
Nasza dokumentacja będzie mieć różne wersje, ale sekcja Informacje o wersji może zawierać 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 najprostszy sposób na uzyskanie informacji od właścicieli/programistów portów (zwłaszcza w przypadku, gdy jest ich niewiele lub nie ma ich wcale). Wstępnie uzupełnię wszystkie informacje, jakie posiadam w istniejącej dokumentacji, i którą można później sprawdzić pod kątem kompletności, dokładności i waluty lub uzupełnić nią w razie potrzeby.
Następnie przejrzę istniejącą dokumentację: README, wiki i witrynę. Będę pisać na nowo i w razie potrzeby dodawać kolejne sekcje do każdej sekcji i pobierać wszystkie informacje do nowego portalu. Zwracam też uwagę na to, jakie informacje są pobierane, aby mieć pewność, że po uruchomieniu portalu nie występują podwójne wartości, sprzeczności i inne anomalie.
W tym czasie będę współpracować z mentorami, programistami, opiekunami portów i innymi ekspertami z danej dziedziny, aby dostarczać im brakujące informacje i dbać o to, aby każda strona była jak najbardziej aktualna i kompletna.
Zgodnie z duchem współpracy i za zgodą mentorów chcę, aby portal strony był dostępny dla społeczności ScummVM przez cały czas trwania procesu pisania, aby otrzymywać opinie w czasie rzeczywistym i mieć pewność, że nic nie umknie Twojej uwadze.
Sugeruję korzystanie ze wskazówek redakcyjnych, takich jak przewodnik po stylu dokumentacji Google dla deweloperów, aby zapewnić spójność tej treści i całej dokumentacji.
W miarę możliwości będę korzystać ze zrzutów ekranu, GIF-ów i innych pomocy wizualnych, aby ułatwić zrozumienie treści.
Proponowany harmonogram:
Nawiązywanie więzi ze 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 treść dokumentu.
Tydzień 1 14 września–20 września
- Utwórz szablon dla stron instalacji na danej platformie.
- Wstępnie wypełnij szablony wszelkimi istniejącymi informacjami i przekaż je odpowiednim podmiotom obsługującym porty/programistom w celu uzyskania dodatkowych informacji.
Tydzień 2 21 września–27 września
- Skonfiguruj nowy portal dla dokumentacji.
Tydzień 3 28 września–4 października
Korzystanie ze ScummVM: – Interfejs – Ustawienia globalne Instalowanie ScummVM: – Przewodniki instalacji związane z określoną platformą, gdy zwracane są mi gotowe szablony.
Tydzień 4 5 października–11 października
Korzystanie ze ScummVM: – Ustawienia gier, – Skróty klawiszowe, Instalowanie ScummVM: – Przewodniki instalacji związane z daną platformą, gdy są zwracane gotowe szablony.
Tydzień 5 12–18 października
Opcje zaawansowane: – Chmura i sieć LAN – Mapowanie sterowania Instalowanie ScummVM: – Przewodniki instalacji związane z daną platformą, gdy wypełnione są gotowe szablony.
Tydzień 6 19–25 października
Opcje zaawansowane: – konfiguracja, – opcje wiersza poleceń, instalowanie ScummVM: – przewodniki instalacji związane z daną platformą, w których do mnie trafiają gotowe szablony.
Tydzień 7 26 października–1 listopada
Opcje zaawansowane: – Grafika, – Dźwięk, Instalowanie ScummVM: – Przewodniki instalacji związane z konkretną platformą, gdy są zwracane 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 przypadku których zwracane są mi wypełnione 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 są jeszcze ukończone.
Tydzień 10 16–22 listopada
- Ostateczna edycja, korekta i finalizacja wszelkich decyzji związanych z portalem, takich jak nawigacja na pasku bocznym, poprawki motywu/CSS itp.
- Upewnij się, że wszystkie linki działają zgodnie z oczekiwaniami.
- Sprawdź, czy obrazy/GIF-y wyświetlają się prawidłowo.
Tydzień 11 23–30 listopada
- Sfinalizuj wszystkie niezwykłe przedmioty i oficjalnie uruchom portal.
- Gdy portal będzie już dostępny, usuń zbędne informacje z innych źródeł na podstawie konsultacji z mentorami.