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:
- GenPipes
- Pisarz techniczny:
- shaloo
- Nazwa projektu:
- Skonfiguruj dokumenty GenPipes na stronie „Read The Document”
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Proponuję 3-etapowy plan związany z osiągnięciem celu skonfigurowania dokumentacji GenPipes w ramach zadania „Czytanie dokumentów”.
Krok 1. PoC
Zapoznaj się z dotychczasową dokumentacją GenPipes jako nowy użytkownik lub badacz
- zidentyfikować brakujące informacje i nieścisłości;
- Proponuj nowe tematy dokumentów (jeśli są wymagane)
- Opracować wersję mapy architektury informacji, aby dotrzeć do docelowych odbiorców z naciskiem na nowych użytkowników.
(Uwaga: podczas tego kroku możemy też potrzebować informacji od mentorów GenPipes dotyczących nowej konfiguracji repozytorium GitHub, w którym można hostować dokumenty genpipes na potrzeby RTD. To repozytorium GitHub może być używane do importowania wszystkich dokumentów w potokach kompilacji RTD. Może to wymagać informacji o regułach repozytorium GenPipes i wytycznych dotyczących zarządzania źródłami dokumentów, jeśli trzeba je przestrzegać. W przeciwnym razie można użyć standardowych. W przypadku osób kontaktowych mogę również zaprezentować przykładową konfigurację repozytorium RTD przy użyciu mojego konta GitHub, np.https://gpdocs.readthedocs.io/en/latest/ (to jest przykładowy program stworzony przeze mnie na potrzeby tej propozycji).
Na podstawie sprawdzenia i analizy z poprzedniego kroku utwórz podstawową strukturę lub indeks proponowanej dokumentacji GenPipes i opublikuj ją w witrynie RTD.
- Obejmuje to utworzenie repozytorium GitHub (np. za pomocą narzędzia Sphinx) i podstawowych plików dokumentacji.
- Obejmuje to również utworzenie nowego spisu treści, który uwzględnia zarówno nowych, jak i doświadczonych użytkowników w różnych sekcjach i przepływach informacji.
Sprawdzanie i zatwierdzanie podstawowego szkieletu spisu treści
W fazie oceny GSoD dla GenPipes próbowałem stworzyć wartość dla GenPipes za pomocą tej próbki hostowanej w RTD. Pamiętaj, że ten link służy wyłącznie do celów demonstracyjnych. Link ten nie jest jeszcze publicznie dostępny w RTD. Niezależnie od tego, czy znajdę się na krótkiej liście, ta wersja demonstracyjna może zostać użyta do szybkiego rozpoczęcia pracy nad rozwojem zespołu GenPipes. Źródła w repozytorium GitHub c3g/GenPipes są już sprawdzone. Mentorzy, Rola i Hector, polubili go podczas rozmowy na Skype, więc pomyślałem, że GSoD Gods też może chcieć go zobaczyć. Na razie jest to szkielet barebone, ale w miarę możliwości planujemy go zaktualizować do 30 lipca.
https://genpipes.readthedocs.io/en/latest/
Krok 2. Tworzenie zestawu dokumentów GenPipes Doc w wersji 0.9
Określ, które bieżące lub istniejące dokumenty GenPipes można importować, łączyć lub konwertować na dokumentację opartą na Sphinxie/rst w celu hostowania na RTD, pamiętając o harmonogramie GSoD.
W razie potrzeby konwertuj zidentyfikowane dokumenty na format rst, twórz nowe dokumenty w odpowiednich przypadkach i używaj ich ponownie w miarę możliwości.
- Zaimportuj ten początkowy zestaw dokumentów do ReadTheDocs jako Proof of Concept – przechowuj go tam jako chronione repozytorium. Umieścić na wstępie notatę sugerującą nowym użytkownikom zapoznanie się z oryginalną dokumentacją GenPipes, dopóki nie zostanie zatwierdzona zmiana.
Sprawdzanie, korygowanie i aktualizowanie
Krok 3. Ulepsz, sprawdź i opublikuj pierwszy projekt w sekcji RTD
Wpisz szczegóły proponowanej nowej struktury dokumentu GenPipes w spisie treści GenPipes – dodaj dodatkowe dokumenty oprócz pierwszych kilku (GenPipes Readme), koncepcje, samouczki itp.
Dodaj wyraźne oznaczenie w spisie treści, aby kierować do nowych użytkowników, doświadczonych użytkowników GenPipes, deweloperów GenPipes itp.
Zaproponuj i omów proces pracy z częściową automatyzacją za pomocą RTD (kompilacji Sphinxa) dotyczący tego, jak można utrzymywać i edytować zestaw dokumentów GenPipes przez użytkowników oraz czy C3G pozwoli na to zewnętrznym współtwórcom dokumentów. Może to wymagać utworzenia wytycznych dotyczących aktualizacji dokumentów, podobnych do wytycznych dotyczących kodowania. Może wymagać wykonania więcej czynności podrzędnych. Automatyczne sprawdzanie pisowni przed zatwierdzaniem zmian w dokumentach GenPipes.
Zgłoś
Na koniec utwórz raport dla GSoD na podstawie doświadczeń, dzienników i opinii mentorów.
Inne uwagi
W przyszłości (po upływie 3 miesięcy) mogę pomóc w dłuższej perspektywie w utrzymaniu GenPipes. Możesz też przeszkolić inne osoby, jeśli to konieczne. Będzie to można przewidzieć w ciągu pierwszych 3 miesięcy.
Proponuję też, aby w ramach projektu utworzyć 3-stronicowy opis projektu w GenPipes, który ułatwi rozpoczęcie pracy. Obecnie nowy użytkownik musi przejść przez wiele etapów, zanim będzie mógł zacząć korzystać z GenPipes, ponieważ dokumentacja jest dobra, ale rozproszona i nieprzyjazna dla nowych użytkowników. Nie wiem, czy da się to zrobić w ciągu 3 miesięcy, ale spróbuję.
Tę samą propozycję i informacje o jej powstaniu (historię) można też wyświetlić na stronie https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing.