Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- Linuks Foundation
- Pisarz techniczny:
- boron
- Nazwa projektu:
- Przekształć dokumentację dotyczącą hostingu i generowania treści oraz tworzenia stron i przewodników dla programistów dotyczących zmiany struktury.
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie :
Dokumentacja ma pomagać użytkownikom i deweloperom w korzystaniu z produktów lub usług. 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, które pojawiają się podczas używania oprogramowania. Obniża również koszty pomocy oraz stanowi część tożsamości korporacyjnej i tożsamości open source usługi – dobra dokumentacja jest oznaką prawidłowego działania usługi i zespołu programistów.
Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak wykonywać powyższe czynności w sposób skuteczny i wydajny. Dokumentacja może odgrywać kluczową rolę w zapewnieniu sukcesu usługi, ponieważ wspaniała komunikacja zawsze jest podstawą każdej firmy i produktu, a doskonała dokumentacja przekształca ją w łatwą do zarządzania strukturą, do której każdy może odnieść sukces.
Każda witryna z dokumentacją potrzebuje dobrego potoku tworzenia i hostowania przepływu pracy. W organizacji takiej jak AGL, która ma wiele wersji i obszerną dokumentację, pliki dokumentacji (znaczniki) są rozłożone w wielu repozytoriach, co sprawia, że utrzymywanie i aktualizowanie ich jest niezwykle złożone i czasochłonne.
Bieżący stan :
- Witryna z dokumentem AGL opiera się na zbiorze plików w formacie 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.
- Prowadzi to do skonfigurowania 4 repozytorium dla procesu kompilacji i hostingu dokumentacji :
- Dokumenty-webtemplate [https://github.com/automotive-grad-linux/docs-webtemplate] : zawiera szablon witryny Jekyll.
- Dokumenty-tools [https://github.com/automotive-grad-linux/docs-tools] : zawiera narzędzia do automatycznego generowania witryn technicznych na podstawie plików Markdown.
- Dokumenty-source [https://github.com/automotive-sta-linux/docs-sources] : źródło (znaczniki [https://github.com/automotive-sta-linux/docs-sources/tree/master/docs]) zawierające ogólne dokumenty i przewodniki.
- Dokumenty-gh-pages [https://github.com/automotive-Grade-linux/docs-gh-pages] : wdrożone repozytorium stron GitHub na potrzeby witryny z dokumentacją [https://gist.github.com/growupboron/docs.automotivelinux.org].
- Narzędzie (skrypt) dostępne w docs-tools [https://github.com/automotive-grad-linux/docs-tools] zajmuje się zbieraniem i tworzeniem szablonów w przypadku wszystkich plików Markdown zgodnie z plikiem fetched_files.yml znajdującym się w szablonie docs-webtemplate [https://github.com/automotive-sta-linux/docs-webtemplate].
- Bieżący przepływ pracy związanej z generowaniem witryny 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, które są pobierane ze zdalnych repozytoriów do szablonu docs-webtemplate [https://github.com/automotive-grad-linux/docs-webtemplate]. Pliki yaml książek zawierają wszystkie adresy URL do plików w formacie Markdown ze zdalnego repozytorium.
- Gdy tylko zostaną pobrane wszystkie pliki Markdown, narzędzia mogą wygenerować stronę z dokumentem 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 (tworzenia i hostingu) można uprościć i uprościć, dzięki czemu deweloperzy będą mogli skupić się na dokumentacji zamiast na procesie generowania i wdrażania dokumentacji.