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:
- Otwórz Collective
- Pisarz techniczny:
- Anna i só
- Nazwa projektu:
- Ulepszenie ogólnej dokumentacji pomocy
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Pierwsze wrażenia Często spotyka się strony z dokumentacją zawierające instrukcje bez dodatkowych multimediów (filmów, GIF-ów czy obrazów), a inne sekcje w tym samym rozdziale zawierają bardziej kompletne wpisy. Na przykład sekcja Edytuj zbiorowy składa się tylko z instrukcji, a Dodaj hosta Fiscal zawiera pliki pomocnicze.
Na stronach, które przeglądałem/przeglądałam, żadne multimedia nie są opisane za pomocą atrybutu tekstu alternatywnego. Brak opisów obrazów utrudnia pełne zrozumienie dokumentacji przez osoby korzystające z czytników ekranu i osoby korzystające z wolniejszego połączenia z internetem, w przypadku których może się nie udać wczytać multimediów.
Niektóre sekcje dokumentacji zawierają najczęstsze pytania i bezpośrednie instrukcje dotyczące poruszania się po interfejsie, np. Zmiana hosta Fiscal. Ponieważ w interfejsie dokumentacji nie ma spisu treści, użytkownik, który zna konsekwencje zmiany w rekordach rejestracji i chce tylko uzyskać obiektywne instrukcje, może uznać dokumentację za zbyt długą i nie na temat.
Chociaż język dokumentacji technicznej jest dość spójny, dostępny publicznie Przewodnik po stylu zawiera zbyt mało informacji o tym, jak należy pisać dokumentację. Ponieważ na stronie Udziela się wspomniano o wpłatach do dokumentacji technicznej, zarówno Open Collective, jak i potencjalni współtwórcy przydałyby się bardziej kompleksowe wytyczne.
Propozycja Proponuję przejrzenie stron pomocy dla użytkowników, aby zmienić ich wygląd i obecną strukturę.
Metodologia i harmonogramChcę ulepszyć dokumentację Open Collective, współpracując ze społecznością i promując cykle ciągłej informacji zwrotnej o zmiennej długości.
Okres nawiązywania kontaktów ze społecznością (1 sierpnia – 1 września 2019 r.): poznawanie społeczności Open Collective. przeprowadzenie wywiadów z aktywnymi członkami zespołów pracujących nad ważnymi i rozpoczynającymi się projektami, aby zapytać ich o obecny stan dokumentacji (raport 1); Zanotuj wszystkie wewnętrzne systemy używane do śledzenia zapytań i problemów oraz proces ich dokumentowania w dokumentach Open Collective (raport 2). Ocena ukrytych problemów w bieżącej wersji dokumentacji i przygotowanie planu ich rozwiązania (raport 3).
2–6 września: pierwszy cykl opinii i korekty, uwzględniający wszystkie komentarze i sugestie społeczności z okresu nawiązywania więzi ze społecznością. Czy nasz plan jest gotowy? Czy trzeba coś zmienić? (Raport nr 4)
9–20 września: opracowanie modelu koncepcyjnego z mniej wypełnionym rozdziałem dokumentacji. Szkic publicznych wskazówek redakcyjnych (raport 5).
23–25 września: przesłanie modelu koncepcyjnego do oceny (grupa zamknięta).
26–27 września: czy nasz dowód koncepcji wymaga wprowadzenia jakichś poprawek przed wdrożeniem? Czy potrzebujemy więcej czasu? Dostosuj je odpowiednio. (Raport 6)
30 września–9 października: wdrożenie modelu koncepcyjnego. Drugi cykl opinii (grupa publiczna).
10–15 października: ostatni cykl oceny i dostosowywania proof of concept. (Raport 7)
16–20 października: krótka przerwa w działalności [1].
21 października – 23 listopada: opublikowano ostateczną wersję przewodnika po stylu (raport 8). Zastosowanie wszystkich instrukcji zawartych w Style Guide do wszystkich stron dokumentacji dla użytkowników (raport 9). Raport podsumowujący wszystkie wykonane działania i kolejne rekomendacje dla społeczności (raport 10).
Na życzenie możemy przedłużyć czas trwania projektu.
[1]: Wycieczka zaplanowana przed złożeniem zgłoszenia do edycji Docs Season.
Wymagania: – 10 publicznych raportów o wykonanych działaniach – publiczny przewodnik po stylu, z którego mogą korzystać zarówno Open Collective, jak i współpracownicy zewnętrzni – ulepszone strony dokumentacji dla użytkowników