Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- The Linux Foundation
- Pisarz techniczny:
- boron
- Nazwa projektu:
- Zmodyfikuj dokumentację hostingu i generowania treści oraz zmień strukturę na stronach z wprowadzeniem i przewodnikach dla programistów.
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
W skrócie :
Dokumentacja ma pomagać użytkownikom i deweloperom w korzystaniu z produktu lub usługi. Dobra dokumentacja jest bardzo ważna, ponieważ pozwala użytkownikom nauczyć się korzystać z oprogramowania, jego funkcji, porad i wskazówek, a także rozwiązywać typowe problemy związane z jego używaniem. Obniża również koszty pomocy i jest częścią tożsamości firmy oraz tożsamości open source : dobra dokumentacja jest oznaką prawidłowego działania usługi i zespołu dewelopera.
Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak skutecznie i wydajnie wykonywać wymienione wyżej czynności. Dokumentacja może odgrywać kluczową rolę w zapewnieniu sukcesu usługi, ponieważ doskonała komunikacja to podstawa każdej firmy i produktu, a doskonała dokumentacja pozwala ją uporządkować i umieścić w łatwym do zarządzania schematem, z którego każdy może odnieść sukces.
Każda witryna z dokumentacją potrzebuje dobrego potoku przepływu pracy przy tworzeniu i hostowaniu przepływu pracy w organizacji takiej jak AGL, która ma wiele wersji i ma dużo szczegółowej dokumentacji. Pliki dokumentacji (znaczniki) są rozłożone w wielu repozytoriach, co sprawia, że obsługa i aktualizowanie ich jest niezwykle skomplikowana i czasochłonna.
Bieżący stan :
- Witryna z dokumentem AGL opiera się na zbiorze plików Markdown pobranych z różnych repozytoriów.
- Strony dokumentu są obecnie hostowane w poszczególnych źródłach jako Markdown przy użyciu silnika projektu Cordova.
- Spowoduje to skonfigurowanie repozytorium na potrzeby procesu tworzenia i hostowania dokumentacji w cztery oczy :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : zawiera szablon witryny Jekyll.
- Dokumenty-tools [https://github.com/automotive-grade-linux/docs-tools] : zawiera narzędzia do automatycznego generowania witryn technicznych na podstawie plików Markdown.
- Dokumenty-źródła [https://github.com/automotive-grade-linux/docs-sources] : źródło (znaczniki [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) zawierające ogólne dokumenty i przewodniki.
- Docs-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] zajmuje się gromadzeniem i tworzeniem szablonów wszystkich plików Markdown zgodnie z pobieranym_plikiem.yml znajdującym się w szablonie docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Bieżący proces generowania strony z dokumentacją usługi 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ążek. Służy do pobierania wszystkich plików yaml książek ze zdalnych repozytoriów do narzędzia docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Pliki yaml książek zawierają wszystkie adresy URL plików Markdown ze zdalnego repozytorium.
- Gdy tylko wszystkie pliki Markdown są pobierane, wdrażane są narzędzia do wygenerowania witryny dokumentu AGL na stronie docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages].
- 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ływów pracy (kompilacji i hostingu) można uprościć i uprościć, dzięki czemu programiści będą mogli w znacznym stopniu skupić się na dokumentacji zamiast na tworzeniu i wdrażaniu dokumentów.