Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- kolibri
- Pisarz techniczny:
- StephDix
- Nazwa projektu:
- Konwencje stylu dokumentacji ekosystemu Kolibri i przepływów pracy
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
W skrócie
Ten dokument szczegółowo opisuje wdrożenie wytycznych dotyczących stylu i zarządzania przepływami pracy w ramach udokumentowanych informacji Learning Equality w projekcie Kolibri.
Opis
Moja oferta pakietowa składa się z 4 faz. W pierwszej fazie udoskonalę Przewodnik po stylu LE Dokumentacja Style Guide oraz wskazówki o ułatwieniach dostępu, opis i zalecenia dotyczące formatu, które są zgodne z koncepcjami i wskazówkami dotyczącymi stylu podczas tworzenia oprogramowania. W drugiej fazie przeprowadzę audyt jakości dokumentów ReadTheDokumentacja i Dokumenty Google. Plan audytu wykorzystuje listy kontrolne do oceny zgodności ze wskazówkami dotyczącymi stylu. Te listy kontrolne pomagają rejestrować wyniki i wprowadzać zmiany w dokumentacji. W trzecim etapie zajmę się strukturą, wyglądem i działaniem szablonów z ReadTheDokumentacja i Dokumenty Google. Utworzę repozytorium na Dysku Google na potrzeby szablonów i obrazów, które wskażę każdą kategorię głównych typów dokumentów do ponownego wykorzystania w przyszłych implementacjach. Uzupełnię to zadanie, tworząc szablony umożliwiające przesyłanie problemów z dokumentami, aby można było je łatwo zidentyfikować podczas weryfikacji próśb o wyciąganie. Na koniec utworzę Przewodnik dla współtwórców, w którym zgrupuję przydatne zasoby dla każdej grupy współpracowników, aby ułatwić im dostęp do informacji.
Cel i zakres
Celem tego planu wdrożenia jest ułatwienie użytkownikom korzystania z dokumentów firmy Kolibri, a także pomoc członkom zespołu i współtwórcom w tworzeniu lepszej dokumentacji i aktywnej współpracy w społeczności. Ta implementacja dotyczy ReadTheDokumentacja i podzbiory dokumentów Google w ekosystemie Kolibri.
Odbiorcy
Główna grupa odbiorców składających się z implementatorów, administratorów i użytkowników, którzy są najbardziej krytycznymi konsumentami dokumentacji Kolibri. Dodatkowa grupa odbiorców składająca się z członków zespołu i współpracowników pracujących nad produkcją i korzystaniem z dokumentacji Kolibri.
Cele
Przewodnik stylistyczny i system przepływu pracy w dokumentacji ekosystemu Kolibri wymaga od użytkowników: tworzenia przystępnej dokumentacji z przystępnym językiem i spójnym układem; Zachowywanie działań związanych z jakością w ramach dokumentacji. Zachowaj łatwy dostęp do informacji między kanałami dokumentacji. Wspieraj inicjatywy współpracy w społeczności open source Kolibri.
Źródła informacji
Źródłami informacji były Kolibri, Kolibri Studio, dokumenty Kolibri Development RTD i narzędzia Kolibri Toolkit z Dysku Google.
Wspaniała organizacja Radina Matic pomogła Ci przygotować ćwiczenia rozgrzewkowe i ćwiczenia związane z projektem. Jej uwagi na temat tego, co organizacja określa jako „Wytyczne” i „Przewodniki”, oraz dotyczące istnienia Przewodnika dla współtwórców pomogły mi uporządkować pomysły i wnioski.
Oprogramowanie
Tworzę wersję roboczą Przewodnika stylów w Dokumentach Google. Platforma dokumentów jest idealna do iteracji, gdy jest gotowa do publikacji. Na potrzeby kontroli jakości przeprowadzę i ocenię dokumenty w Formularzach Google. Odpowiedzi na pytania z formularza będą przechowywane w arkuszu kalkulacyjnym. Refaktoryzuję dokumenty RTD przy użyciu GitHuba. Pracuję w usługach Git, Gitkraken, GitHub i Gitlab. Znam praktyczną znajomość języka Markdown i kilka tekstu RestructuredText. W dalszym ciągu chcę publikować poprawki w dokumentacji, aby poznać składnię. Do obrazów i GIF-ów będę używać Sharex. Uwielbiam to narzędzie, ponieważ renderuje się w różnych formatach wyjściowych. Wykorzystam diagramy i do edycji obrazów. Oprogramowanie Diagramy doskonale integruje się z Dokumentami Google, Dyskiem Google i LibreOffice. Stan dokumentacji Na etapie eksploracji poprawiłem większość dokumentacji Kolibri. W większości dokumentacji projektu znaleziono błędy gramatyczne, literówki, niespójności w układzie, typografii, użyciu obrazów, a także mylące ścieżki w dokumentacji. Na przykład w przewodniku użytkownika Kolibri sekcja dotycząca rozwiązywania problemów jest podtematem, a nie tematem. Takie informacje są na tyle istotne, aby użytkownicy mogli uzyskać do nich dostęp ze spisu treści. Zamiast tego mogą skorzystać z paska wyszukiwania i drzewa spisu treści, aby rozwinąć inne tematy i znaleźć artykuły na temat rozwiązywania problemów.
Aby otworzyć sekcję „Rozwiązywanie problemów”, wyszukaj ją lub rozwiń sekcję „Zarządzaj Kolibri”, aby zobaczyć, że funkcja rozwiązywania problemów jest dostępna w dokumentacji. Przewodnik a wskazówki Na potrzeby tej propozycji projektu przeanalizowałam dwa dokumenty: Przewodnik stylistyczny dotyczący dokumentacji użytkownika LE Kolibri oraz wytyczne dotyczące tłumaczenia na język LE. W przewodniku LE Kolibri zamieściłam zalecenia i komentarze związane z proponowanym zarysem tematu i planem dokumentacji oraz kilka innych kwestii, które wymagają poprawy. W wytycznych dotyczących tłumaczeń LE zmieniłem format i styl zgodnie z zaleceniami i dotychczasowymi konwencjami przedstawionymi w przewodniku po stylu. W trakcie analizy najbardziej zwróciło moją uwagę na błędne przekonanie, że dokumenty zostały skategoryzowane jako Przewodnik i Wytyczne.
Rezultaty
Oprócz sugestii i komentarzy wraz z wstępnym formularzem, które szczegółowo wyjaśnię w zadaniu kontroli jakości, przeprowadzono kontrolę jakości podręcznika tłumaczenia LE. Oto kilka końcowych komentarzy uzyskanych z oceny: Uszkodzone linki do witryny .js o składni ICU Format użyty do utworzenia tych wytycznych jest nieprawidłowy. Dokument jest przewodnikiem, a nie wytycznymi. Niespójna typografia. Niewłaściwe użycie nagłówków i tytułów, niewłaściwy język i niewłaściwe użycie skrótów. Niewłaściwe użycie tekstów alternatywnych. Powtarzające się twierdzenia lub instrukcje.
Wyniki z obu dokumentów są częścią projektu dostawy.
Zadania związane z projektem
- Rekomendacje dotyczące przewodnika po stylu dokumentacji użytkownika LE (komentarze)
- Wytyczne dotyczące tłumaczenia LE z nowymi stylami i formatami.
- Konspekt tematu
- Oś czasu projektu
- Zadania związane z dokumentacją