Ta strona zawiera szczegóły projektu technicznego do pisania w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- CERN-HSF
- Pisarz techniczny:
- SabitaR
- Nazwa projektu:
- Restrukturyzacja i uproszczenie dokumentacji Allpix Squared
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
PRZEGLĄD Wybrałem projekt Allpix Squared CERN-HSF z 2 głównych powodów:
Rozwijanie umiejętności: dotychczasowa dokumentacja tego projektu jest obszerna i integruje wiele formatów treści. Przeprowadzenie audytu i przekształcenie tego obszernego pakietu dokumentów pomoże mi udoskonalić architekturę informacji i umiejętności pisania. Poza tym obszar projektu (fizyka cząstek) jest dla mnie nowy. To dla mnie wyzwanie, aby doskonalić swoje umiejętności w interakcjach z programistami. Uważam, że autorzy treści technicznych mogą przetwarzać dane wejściowe od deweloperów i prezentować przydatne treści dla użytkowników na każdym poziomie, jeśli tylko przeprowadzimy wymagane badania wstępne i zadamy odpowiednie pytania. Ten projekt pozwoli mi to sprawdzić.
Wiedza techniczna: Ten projekt wymaga Hugo – narzędzia, które jest na szczycie mojej listy rzeczy do nauczenia się. Nie mogę się doczekać, aż poznam proces LaTeX-Markdown-Hugo-GitLab-CI.
W fazie eksploracji pracy technicznego autora poznałam mentorów projektu i zapoznałam się z istniejącą strukturą pakietu dokumentów. Stworzyłem też witrynę demonstracyjną (https://ap2-demo.netlify.app/), aby sprawdzić, czy mogę prawidłowo skonfigurować Hugo i Docsy na komputerze z systemem Windows. Udało mi się wdrożyć stronę w Netlify, ale nie w Gitlab Pages. Aby ten projekt zachował swój obecny proces wdrażania, znajdę sposób na wdrożenie motywu Hugo Docsy do Gitlab Pages.
OCZEKIWANE EFEKTY PROJEKTU: – Usprawniona strona projektu, która integruje dokumentację, referencje kodu, samouczki i wiadomości. – przebudowany i zrewidowany podręcznik użytkownika, który oddziela treści przeznaczone dla użytkowników i programistów oraz zawiera informacje, których wcześniej brakowało. – Samouczki z dostępnymi przykładami dokumentacji, odpowiedziami na najczęstsze pytania i omówieniem typowych problemów.
NARZĘDZIA PROJEKTOWE: obecna dokumentacja Allpix Squared korzysta z programów LaTeX, Doxygen, pandoc i Hugo, a także GitLab i Gitlab CI. Mentorzy projektu i ja rozmawialiśmy o możliwości przeniesienia treści z LaTeXa do Markdowna za pomocą wtyczek MathJax. Jeśli mi się uda, przepływ pracy nad dokumentami będzie obejmował Hugo, Markdown, Doxygen, git i Gitlab CI. Aby samouczki były dostępne na tej samej stronie/platformie, będę korzystać z Hugo i Markdown. Chcę się dowiedzieć, czy można używać ćwiczeń z programowania jako narzędzia do samouczenia. W lipcu chcę przetestować proces ClaaT-Hugo i omówić go z mentorami, jeśli zostanę wybrana.
CZAS TRWANIA PROJEKTU Proszę o ukończenie projektu Allpix Squared w standardowym 3-miesięcznym okresie (14 września – 30 listopada 2020 r.). W tym czasie będę spędzać na nim około 15 godzin tygodniowo. Te godziny obejmują spotkania z mentorem i związane z nimi e-maile. Będę też przestrzegać harmonogramu GSoD w zakresie budowania więzi w społeczności i finalizacji projektu.
ZADANIA PROJEKTU Oto, jak zamierzam wprowadzić proponowane aktualizacje w obecnym pakiecie dokumentów Allpix Squared: 1. Przeprowadź badania, omów możliwości i sprawdź opcje (17 sierpnia–13 września 2020 r.): – Zapoznaj się z wymaganiami projektu. – Zainstaluj oprogramowanie Allpix Squared, aby zidentyfikować brakujące informacje w bieżących dokumentach. – poproś o wymagane dane logowania. – Tworzenie przepływów pracy użytkowników w Allpix Squared – Klasyfikowanie treści według roli użytkownika – Sprawdzanie konsekwencji konwersji plików LaTeX na Markdown – Konsolidowanie repozytoriów źródłowych lub poznawanie sposobu pracy z kilkoma repozytoriami Git – Bonus: testowanie CLaaT jako opcji dla samouczków – Bonus: tworzenie krótkiego przewodnika po stylach lub skrótów, aby ułatwić współtwórcom utrzymywanie dokumentów Harmonogram: etap budowania więzi z użytkownikami
przebudowa, sprawdzenie i ulepszanie treści (14 września–19 października 2020 r.): 2 zadania tygodniowo, każde zajmuje około 5–7 godzin. Ten harmonogram obejmuje tydzień buforowy na wypadek nieoczekiwanych opóźnień lub problemów.
- Sprawdzanie istniejących treści i klasyfikacji użytkowników z uwzględnieniem ich przepływów pracy
- Omówienie i testowanie przepływu pracy dotyczącego treści zrestrukturyzowanych dla różnych użytkowników
- Pozyskiwanie i ulepszanie brakujących treści
- Konwertowanie plików LaTeX na format Markdown
- Dokończ spis treści przewodnika użytkownika i przewodnika dla programistów
- generować pliki PDF z przewodnikami dla użytkowników i programistów;
- Bonus: uporządkuj treści samouczków na podstawie przykładów i problemów
- Bonus: skonfiguruj przepływ pracy dotyczący samouczka z przykładami.Harmonogram: 5 tygodni (faza tworzenia dokumentów)
Tworzenie witryny (19 października – 30 listopada 2020 r.): 1–2 zadania tygodniowo, ok. 5–7 godzin na zadanie. Ten harmonogram obejmuje tydzień na rozwiązanie problemów i dopracowanie ostatecznego wyniku.
- Poznanie i przetestowanie procesu publikowania
- Tworzenie struktury witryny za pomocą Hugo i Docsy
- Testowanie sposobu utrzymywania bieżącego wdrażania automatycznego i przepływu pracy za pomocą Dokumentów Google
- Pobieranie treści z Doxygen
- Tworzenie podręcznika użytkownika, przewodnika dla programistów i samouczków z treściami w formacie LaTeX lub Markdown
- Dokończ wygląd witryny projektu (logo, kolory, szablon, układ, linki, łatwość obsługi i program Gitlab CI/CD). Harmonogram: 6 tygodni (faza opracowywania dokumentów)