Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon 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
OMÓWIENIE Wybrałem projekt Allpix Squared od CERN-HSF z dwóch powodów:
Rozwijanie umiejętności: Obecna dokumentacja tego projektu jest wyczerpująca i obejmuje wiele formatów treści. Kontrola i restrukturyzacja tego rozbudowanego pakietu dokumentów pomoże mi udoskonalić architekturę informacji i umiejętności pisania. Poza tym domena projektu (fizyka cząstek elementarnych) jest dla mnie nowością. Zachęca mnie do szlifowania umiejętności interakcji z programistami. Uważam, że twórcy zajmujący się tematyką techniczną mogą przetwarzać informacje przekazywane przez deweloperów i prezentować przydatne treści różnym poziomom użytkowników, JEŚLI przeprowadzimy wymagane badania i zadamy odpowiednie pytania. Dzięki temu projektowi przetestuję tę teorię.
Wiedza techniczna: Ten projekt wymaga Hugo – narzędzia, które znajduje się na samej górze listy do nauki. Nie mogę się doczekać, aż poznam przepływ pracy LaTeX-Markdown-Hugo-GitLab-CI.
Na etapie eksploracji pisarza technicznego udało mi się przez krótki czas porozmawiać z mentorami zajmującymi się projektem i zapoznać się z obecną strukturą pakietów dokumentów. Utworzyłem też witrynę demonstracyjną (https://ap2-demo.netlify.app/), aby sprawdzić, czy mogę poprawnie skonfigurować Hugo i Dokumenty na moim komputerze z systemem Windows. Udało mi się wdrożyć witrynę w Netlify, ale nie na stronach Gitlab. Aby umożliwić zachowanie bieżącego przepływu pracy wdrożeniowego dla tego projektu, poszukam sposobu na wdrożenie motywu Hugo Docsy na stronach Gitlab.
OCZEKIWANE WYNIKI PROJEKTU – Uproszczona witryna projektu zawierająca dokumentację, kod, samouczki i wiadomości. – Zmieniony i przejrzysty podręcznik użytkownika, który oddziela treści przeznaczone dla użytkowników i programistów oraz zawiera brakujące informacje. – Samouczek zawierający przykłady instrukcji, odpowiedzi na najczęstsze pytania i najczęstszych problemów.
NARZĘDZIA PROJEKTOWE Obecna dokumentacja Allpix Squared korzysta z narzędzi LaTeX, Doxygen, pandoc i Hugo, a także z GitLab i Gitlab CI. Opiekunowie projektu wspólnie z mentorami rozmawialiśmy o możliwości przeniesienia treści z LaTeX do Markdown za pomocą wtyczek MathJax. Jeśli mi się uda, przepływ pracy związany z dokumentem będzie obejmował Hugo, Markdown, Doxygen, git i Gitlab CI. Aby samouczki pozostały na tej samej stronie/platformie, użyję Hugo i Markdown. zastanawiam się, czy w przypadku samouczków można wykorzystać model ClaaT (Codelabs-as-a-Tool). Mam nadzieję, że w lipcu przetestuję przepływ pracy ClaaT-Hugo i omówię go z mentorami, jeśli zostaną wybrani.
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 poświęcam na to około 15 godzin tygodniowo. Godziny te obejmują spotkania z mentorami i e-maile powiązane z wydarzeniami. Będę też przestrzegać terminów GSoD w zakresie budowania relacji ze społecznością i finalizowania projektów.
ZADANIA W PROJEKCIE Oto jak zamierzam wdrożyć proponowane aktualizacje w istniejącym pakiecie dokumentów Allpix Squared: 1. Zbierz informacje, przedyskutuj je i poznaj opcje (17 sierpnia – 13 września 2020 r.): – Zrozumienie wymagań projektu – Zainstaluj oprogramowanie Allpix Squared, aby znaleźć brakujące informacje w bieżących dokumentach. – Poproś o wymagane dane logowania. – Tworzenie przepływów pracy użytkowników dla różnych użytkowników Allpix Squared – klasyfikowanie treści według roli użytkownika; – sprawdzanie wpływu konwersji plików LaTeX na format Markdown. – Skonsolidowanie repozytoriów źródłowych lub informacje o korzystaniu z wielu repozytoriów git. – Bonus: przetestuj CLaaT jako opcję dostępną w przypadku samouczków. – Dodatkowe informacje: utwórz krótkie wskazówki dotyczące stylu lub skróty w Społeczności
Zmień strukturę, przejrzyj i ulepsz treści (14–19 października 2020 r.): 2 zadania w tygodniu, około 5–7 godzin na zadanie. Obejmuje on tydzień bufora na wypadek niespodziewanych opóźnień lub problemów.
- Sprawdzaj dotychczasowe treści i klasyfikacje użytkowników pod kątem przepływów pracy użytkowników
- Opracuj zarys i przetestuj przepływ pracy ze zmienioną treścią w przypadku różnych użytkowników
- Pozyskiwanie i ulepszanie brakujących treści
- Konwertowanie plików LaTeX na format Markdown
- Finalizowanie spisu treści przewodnika użytkownika i przewodnika dla programistów
- Generowanie plików PDF z przewodnikami użytkownika i dla programistów
- Dodatkowo: utwórz strukturę treści samouczków na podstawie przykładów i problemów
- Dodatkowo: przygotowanie samouczka dotyczącego przykładowych instrukcji Oś czasu: 5 tygodni (faza tworzenia dokumentu)
Tworzenie witryny (19 października – 30 listopada 2020 r.): 1–2 zadania tygodniowo, około 5–7 godzin na zadanie. Obejmuje on tydzień bufora w celu rozwiązania problemów i dopracowania ostatecznych wyników.
- Poznawanie i testowanie procesu publikowania
- Utwórz strukturę witryny za pomocą Hugo i Dokumentów
- Przetestuj przy użyciu Dokumentówy, jak utrzymywać bieżące automatyczne wdrożenie i przepływ pracy
- Pobieranie treści z Doxygen
- Twórz podręczniki użytkownika, przewodnik dla programistów i samouczki na podstawie materiałów LaTex i Markdown
- Ostateczny wygląd i styl witryny projektu (logo, kolory, szablon, układ, linki, użyteczność oraz Gitlab CI/CD) Oś czasu: 6 tygodni (faza tworzenia dokumentów).