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:
- Kolibri
- Pisarz techniczny:
- StephDix
- Nazwa projektu:
- Konwencje dotyczące stylu dokumentacji i przepływów pracy w systemie Kolibri
- Długość projektu:
- Długotrwałe (5 miesięcy)
Opis projektu
Streszczenie
Ten dokument zawiera szczegółowe informacje o wdrożeniu wytycznych dotyczących stylu i zarządzania przepływem pracy w dokumentacji Learning Equality na potrzeby projektu Kolibri Ecosystem.
Przegląd
Moja propozycja składa się z 4 etapów. W pierwszym etapie uzupełnię Przewodnik po stylu dokumentacji LE o wskazówki dotyczące ułatwień dostępu, pisania i formatowania, stosując się do koncepcji i wskazówek dotyczących stylu w ramach rozwoju oprogramowania. W drugiej fazie przeprowadzę audyt jakości dokumentów w ReadTheDocs i Dokumentach Google. Plan audytu obejmuje korzystanie z list kontrolnych w celu oceny zgodności ze wskazówkami dotyczącymi stylu. Te listy kontrolne pomogą Ci rejestrować wyniki i wdrażać zmiany w dokumentacji. W trzeciej fazie zajmę się strukturą, wyglądem i sposobem działania szablonów z dokumentów ReadTheDocuments i Dokumentów Google. Utworzę na Dysku Google repozytorium szablonów i obrazów identyfikujące każdą kategorię szablonów głównych typów dokumentów do wykorzystania w przyszłych implementacjach. Uzupełnię to zadanie, tworząc szablony do przesyłania problemów z dokumentami, aby ułatwić ich identyfikację podczas sprawdzania zgłoszeń. Na koniec utworzymy Przewodnik dla współtwórców, który będzie zawierał 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 poprawa wrażeń użytkowników korzystających z dokumentów Kolibri oraz pomoc członkom zespołu i współtwórcom w tworzeniu lepszej dokumentacji i aktywnej współpracy w społeczności. Ta implementacja dotyczy ReadTheDocs i podzbiorów dokumentów Dokumentów Google w ekosystemie Kolibri.
Odbiorcy
Główna grupa odbiorców to implementatorzy, administratorzy i użytkownicy końcowi, którzy są najważniejszymi odbiorcami dokumentacji Kolibri. Dodatkowa grupa odbiorców składająca się z członków zespołu i współpracowników zajmujących się produkcją i korzystaniem z dokumentacji Kolibri.
Cele
System dokumentacji Kolibri Ecosystem oparty na przewodniku stylu i przepływie pracy wymaga od użytkowników: tworzenia przystępnej dokumentacji z dostępnym językiem i spójnym układem. Stosuj się do zasad dotyczących jakości po udokumentowaniu dokumentacji. muszą zapewniać łatwy dostęp do informacji między kanałami dokumentacji. Wzmacnianie inicjatyw 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 Kolibri Toolkits z Dysku Google.
Fantastyczna Radina Matic okazała się pomocna w realizacji zadań rozgrzewkowych i konkretnych związanych z projektem. Jej uwagi dotyczące koncepcji organizacji jako „wytyczne” i „poradników” oraz informacje o istnieniu Przewodnika dla współtwórców pomogły mi uporządkować pomysły i wersje robocze wniosków.
Oprogramowanie
Opracowanie wersji roboczej przewodnika po stylu w Dokumentach Google. Ta platforma do tworzenia dokumentów jest idealna do wielokrotnego ulepszania dokumentu, gdy jest gotowy do publikacji. W ramach kontroli jakości będę używać Formularzy Google do przeprowadzania i oceny dokumentów. Arkusz kalkulacyjny będzie przechowywać odpowiedzi z formularzy w celu kontroli dokumentów. Przerobię dokumenty RTD za pomocą GitHuba. Pracowałem z Git, Gitkraken, GitHub i Gitlab. Mam praktyczną wiedzę na temat języka Markdown i kilku elementów RestructuredText. Planuję wnosić poprawki do dokumentacji, aby dalej uczyć się składni. Do przesyłania obrazów i GIF-ów będę używać Sharex. Uwielbiam to narzędzie, ponieważ renderuje się w różnych formatach wyjściowych. Do tworzenia diagramów i edycji obrazów użyję Diagrams. Oprogramowanie do tworzenia diagramów świetnie integruje się z Dokumentami Google, Dyskiem Google i LibreOffice. Stan dokumentacji W fazie eksploracji zaktualizowałem większość dokumentacji Kolibri. Znalazłem błędy gramatyczne, literówki, niespójności w układzie, typografii i użyciu obrazów oraz mylące ścieżki dokumentacji w większości dokumentów projektu. Na przykład w przewodniku użytkownika Kolibri sekcja rozwiązywania problemów jest podtematem, a nie tematem. Te informacje są na tyle ważne, że użytkownicy powinni mieć do nich dostęp z poziomu spisu treści. Drugą opcją jest użycie paska wyszukiwania i drzewa spisu treści, aby rozwinąć inne tematy i znaleźć artykuły dotyczące rozwiązywania problemów.
Aby uzyskać dostęp do sekcji „Rozwiązywanie problemów”, musisz ją wyszukać lub rozwinąć sekcję „Zarządzanie Kolibri”, aby zobaczyć, że sekcja „Rozwiązywanie problemów” znajduje się w dokumentacji. Przewodnik a wytyczne W przypadku tego projektu przeanalizowałam 2 dokumenty: Przewodnik po stylu dokumentacji użytkownika Kolibri i Wytyczne dotyczące tłumaczenia w Kolibri. W przewodniku LE Kolibri zawarłam rekomendacje i komentarze na podstawie proponowanego przeze mnie zarysu tematu oraz planu dokumentacji, a także inne kwestie, które wymagają poprawy. W przypadku wytycznych dotyczących tłumaczenia w języku angielskim zmieniłam format i styl na podstawie własnych rekomendacji i dotychczasowych konwencji w przewodniku po stylu. Podczas tej analizy zwróciłem szczególną uwagę na błędne przekonanie dotyczące dokumentów zaklasyfikowanych jako „Przewodnik i wytyczne”.
Rezultaty
Przeprowadziłam kontrolę jakości w przypadku Przewodnika po tłumaczeniu w języku angielskim, a także sugestie i komentarze za pomocą wstępnego formularza, który opisuję szczegółowo w zadaniu dotyczącym kontroli jakości. Oto kilka końcowych komentarzy uzyskanych podczas oceny: Nieprawidłowe linki do witryny ICU Syntax .js 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ściwe użycie języka i niewłaściwe użycie skrótów. nieprawidłowego użycia tekstów alternatywnych; Powtarzanie instrukcji lub instrukcji.
Wyniki dotyczące obu dokumentów są częścią informacji dostarczanych w ramach tej propozycji.
Zadania związane z projektem
- LE User Documentation Style Guide recommendations (comments)
- LE Translation Guidelines z nowymi stylami i formatem.
- Outline
- Oś czasu projektu
- Dokumentowanie zadań