Ta strona zawiera szczegóły projektu dotyczącego przygotowywania tekstów technicznych, który został przyjęty do programu Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- The Linux Foundation
- Pisarz techniczny:
- boron
- Nazwa projektu:
- Rework the documentation hosting &generation and Restructure getting started pages and developer guides.
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie :
Dokumentacja ma pomóc użytkownikom i programistom w korzystaniu z produktu lub usługi. Dobra dokumentacja jest bardzo ważna, ponieważ umożliwia użytkownikom poznanie oprogramowania, jego funkcji, wskazówek i trików, a także rozwiązanie typowych problemów, które mogą wystąpić podczas korzystania z oprogramowania. Zmniejsza też koszty pomocy technicznej i jest częścią tożsamości korporacyjnej i open source produktu. Dobra dokumentacja świadczy o kondycji produktu i zespołu programistów.
Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak skutecznie i wydajnie wykonywać powyższe czynności. Dokumentacja może odgrywać kluczową rolę w zapewnieniu sukcesu produktu, ponieważ dobra komunikacja jest i zawsze będzie podstawą każdej firmy lub produktu. Dobra dokumentacja po prostu przenosi tę komunikację do zarządzalnego frameworka, do którego każdy może uzyskać dostęp, aby osiągnąć sukces.
Każda witryna z dokumentacją wymaga dobrego przepływu pracy związanego z tworzeniem i hostingiem. W organizacji takiej jak AGL, która ma wiele wersji i obszerną dokumentację, pliki dokumentacji (markdown) są rozproszone w wielu repozytoriach, co sprawia, że ich utrzymywanie i aktualizowanie jest niezwykle złożone i czasochłonne.
Bieżący stan :
- Witryna z dokumentacją AGL jest oparta na zbiorze plików markdown pobranych z różnych repozytoriów.
- Strony z dokumentacją są obecnie hostowane w poszczególnych źródłach jako markdown przy użyciu silnika projektu Cordova.
- Powoduje to, że proces tworzenia i hostingu dokumentacji wymaga 4 repozytoriów :
- Docs-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.
- 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ę zbieraniem i szablonowaniem wszystkich plików markdown zgodnie z plikiem fetched_files.yml znajdującym się w docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- Aktualny przepływ pracy związany z generowaniem 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. Pobiera wszystkie pliki yaml książki z repozytoriów zdalnych do docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. Pliki yaml książki zawierają wszystkie adresy URL do plików markdown z repozytorium zdalnego.
- Gdy wszystkie pliki markdown zostaną pobrane, narzędzia generują witrynę z dokumentacją AGL w docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], która jest odpowiednio wdrażana.
- Obecny proces utrzymywania potoku nie jest przyjazny dla użytkowników i programistów, zwłaszcza dla nowych współtwórców. Ten przepływ pracy (tworzenia i hostingu) można uprościć i usprawnić, aby programiści mogli skupić się na dokumentacji, a nie na utrzymywaniu przepływu pracy związanego z generowaniem i wdrażaniem dokumentacji.