Obecny etap:
Program Sezon Dokumentów 2020 zakończył się 15 marca 2021 r. Zobacz oś czasu.
Ta strona zawiera wskazówki dla twórców treści technicznych dotyczące tworzenia raportu po zakończeniu prac nad tegorocznym sezonem Dokumentów.
Przesyłanie raportu dotyczącego projektu
Po rozpoczęciu fazy finalizacji projektu będzie można przesłać raport z projektu, wypełniając formularz, który jest dostępny w sekcji dotyczącej finalizacji projektu w przewodniku technicznym dla twórców.
Informacje do uwzględnienia w raporcie dotyczącym projektu
W tej sekcji opisujemy, jakie informacje można podać w raporcie dotyczącym projektu. Formularz raportu dotyczącego projektu będzie zawierał pola tekstowe oraz pytania jednokrotnego wyboru.
Link do zadania
Podaj link do opisu wykonanej pracy.
Link powinien prowadzić do dokumentu zawierającego krótki opis wykonanej pracy, dokumentację związaną z połączeniem projektu open source z repozytorium, podsumowanie bieżącego stanu projektu oraz listę wyzwań i wniosków.
Link pojawi się w opublikowanych w witrynie wynikach wyszukiwania sezonu dokumentów. Opublikowane wyniki odzwierciedlają zadania ukończone w ramach programu. Opublikowane wyniki to także świetny sposób na powrót do swojej pracy w CV.
Udostępnij link mentorowi i poproś o weryfikację, zanim prześlesz raport o projekcie.
Wymagania dotyczące raportu o projekcie
Weź pod uwagę te wymagania:
- Treści, do których prowadzą linki, muszą ułatwiać użytkownikom rozpoznanie pracy wykonanej w tym czasie, czyli zmian wprowadzonych przez Ciebie lub nowej dokumentacji.
- Praca powinna znajdować się w stabilnym miejscu. Po przesłaniu pliku adresu URL nie można go już zmienić.
Ktoś inny powinien mieć możliwość wykorzystania treści w miejscu docelowym linku (lub odniesienia do niego), aby wykorzystać Twoją pracę.
- Jeśli Twoja praca jest w 100% ukończona, inne osoby powinny mieć możliwość skorzystania z niej.
- Jeśli Twoja praca nie została w 100% ukończona, powinna być jasne, co należy zrobić.
Dobre przykłady opisania swojej pracy
Nie musisz wykonywać wszystkich tych czynności, ale możesz spełnić te wymagania, korzystając z tych rozwiązań:
Utwórz posta na blogu, stronę internetową lub publiczny katalog GitHub z opisem wykonanej pracy oraz linkami do wykonanych zatwierdzeń i repozytoriów. Jeśli jest jeszcze coś do zrobienia, dołącz opis tej pracy. Możesz też udostępnić najciekawsze fragmenty lub wyzwania.
To najlepsza opcja, bo pozwala zawrzeć dużo informacji. Dobrze, że w jasny sposób pokazuje on Twoją pracę, a inne osoby mogą z łatwością zrozumieć Twój wkład.
Możesz użyć tego linku, jeśli korzystasz z GitHuba i 1 żądanie pull Twojej pracy obejmuje całą Twoją pracę.
- Upewnij się, że opis żądania pull jest szczegółowy.
- Upewnij się, że opis jasno informuje, że utwór dotyczy sezonu Dokumentów.
- Jeśli żądanie pull po zakończeniu sezonu Dokumentów będzie wymagało dodatkowej pracy, pamiętaj o uwzględnieniu tego faktu w poprzednim sezonie Dokumentów.
- Ta metoda dostarczania raportu dotyczącego projektu ma tę zaletę, że zawiera w jednym miejscu historię zmian, listę zatwierdzeń i komentarze do weryfikacji.
Jeśli Twoje repozytorium GitHub jest przeznaczone tylko do użytku w sezonie dokumentów, dodaj plik README ze szczegółami Twojej pracy.
Na Dysku Google utwórz folder publiczny i umieść w nim wszystkie utworzone przez siebie poprawki.
Utwórz publiczny arkusz kalkulacyjny w Arkuszach Google i wymień wszystkie zatwierdzenia.
Dodaj link do pojedynczego problemu w publicznym narzędziu do śledzenia błędów, które zawiera jednoznaczne odniesienia do Twojej pracy i innych odpowiednich informacji. Problem powinien śledzić całą Twoją pracę. Upewnij się, że problem zawiera listę wszystkich zatwierdzeń lub że można je łatwo znaleźć w inny sposób.
Link do ujednoliconego procesu lub różnic kontekstowych zmian. Pamiętaj, aby dodać nagłówek zawierający nazwę projektu technicznego oraz informacje o tym, kim jesteś, dzięki czemu będą przydatne dla innych.
Złe przykłady sposobu opisania swojej pracy
Nie rób takich rzeczy:
- Link do pliku tarball lub pliku pocztowego zawierającego cały kod źródłowy projektu lub katalog roboczy.
- Link do górnej części podstawowego repozytorium źródłowego projektu. Jeśli na przykład pracujesz nad cpythonem, ten link nie jest przydatny: https://github.com/python/cpython.
- Link do Twojej kopii repozytorium źródłowego projektu. Ciężko jest zobaczyć, co wprowadzasz w swoich zmianach, ponieważ Twoja praca została mieszana z pracami innych osób.
- Link do opisu projektu na stronie Season of Docs.
Dla mentorów
Pomóż swojemu redaktorowi technicznemu utworzyć odpowiedni raport z projektu. Pamiętaj, aby to zrobić przed stworzeniem własnej oceny pracy autora tekstu technicznego.
Wykonaj te czynności:
- Przesłane zgłoszenie musi spełniać powyższe wymagania.
- Przesłane zgłoszenie musi zawierać opis wykonanych zadań, wymagania oraz powody podjęcia konkretnych decyzji.
Ideą sezonu dokumentów nie jest to, żeby autorzy techniczni mogli zrezygnować z mnóstwa dokumentów. Zadanie może też przydać się przy hostowaniu projektu open source.