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:
- Podstawy Linuksa
- Pisarz techniczny:
- boron
- Nazwa projektu:
- Zmienić sposób hostowania i generowania dokumentacji oraz zmienić strukturę stron z pierwszymi krokami i przewodnikami dla programistów.
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie :
Dokumentacja ma ułatwić użytkownikom i deweloperom korzystanie z produktu lub usługi. Dobra dokumentacja jest bardzo ważna, ponieważ umożliwia użytkownikom zapoznanie się z korzystaniem z oprogramowania, jego funkcjami, poradami i sztuczkami, a także rozwiązywanie typowych problemów występujących podczas korzystania z oprogramowania. Pozwala też obniżyć koszty obsługi i jest częścią tożsamości korporacyjnej oraz open source produktu : dobra dokumentacja jest oznaką jakości produktu i zespołu programistów.
Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak skutecznie i efektywnie wykonywać opisane powyżej czynności. Dokumentacja może odgrywać kluczową rolę w osiąganiu sukcesu przez produkt, ponieważ skuteczna komunikacja zawsze będzie podstawą każdego biznesu lub produktu. Dobra dokumentacja porządkuje tę komunikację w ramy, do których każdy może mieć dostęp, co zwiększa szanse na sukces.
Każda witryna z dokumentacją wymaga dobrego procesu tworzenia i hostowania. W organizacji takiej jak AGL, która ma wiele wersji i dużo szczegółowej dokumentacji, pliki dokumentacji (markdowny) są rozproszone po wielu repozytoriach, co sprawia, że ich utrzymywanie i aktualizowanie jest bardzo skomplikowane i czasochłonne.
Bieżący stan :
- Witryna z dokumentacją AGL opiera się na kolekcji plików markdown pobieranych z różnych repozytoriów.
- Strony dokumentów są obecnie hostowane w poszczególnych źródłach jako markdown za pomocą mechanizmu projektu Cordova.
- W ten sposób powstaje 4 repozytorium dla procesu kompilacji i hostowania dokumentacji :
- Document-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : zawiera szablon witryny Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : zawiera narzędzia do automatycznego generowania witryny technicznej z plików Markdown.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : źródło (markdown [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) ogólnych dokumentów i przewodników.
- Document-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : wdrożone repozytorium stron GitHub dla witryny z dokumentacją [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Narzędzie (skrypt) dostępne w docs-tools [https://github.com/automotive-grade-linux/docs-tools] odpowiada za zbieranie i tworzenie szablonów wszystkich plików markdown zgodnie z plikiem fetched_files.yml znajdującym się w docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Obecny proces generowania witryny z dokumentacją agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing].
- Plik section_version.yml zawiera linki do wszystkich plików yaml książki. Przesyła on wszystkie pliki yaml książki z odległych repozytoriów do szablonu strony internetowej docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Pliki yaml książek zawierają wszystkie adresy URL plików Markdown z repozytorium zdalnego.
- Gdy tylko zostaną pobrane wszystkie pliki Markdown, narzędzia do wygenerowania witryny z dokumentem AGL na stronie docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] zostaną wdrożone.
- Obecny proces utrzymywania potoku nie jest przyjazny dla użytkowników i programistów, zwłaszcza dla nowych współtwórców. Ten potok przepływu pracy (tworzenia i hostowania) można uprościć i udoskonalić, aby deweloperzy mogli skupić się na tworzeniu dokumentacji, a nie na generowaniu dokumentacji i przepływie pracy związanej z wdrożeniem.