Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- Creative Commons
- Pisarz techniczny:
- nimishnb
- Nazwa projektu:
- Przewodnik po posługiwaniu się słownictwem
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie projektu
Słownictwo ma ogromny potencjał, aby można było wykorzystać go jako podstawową bibliotekę komponentów UI do tworzenia stron internetowych. Potrzebuje solidnego, ale przystępnego przewodnika dla laików. Ważne informacje dla programistów, takie jak przewodniki po komponentach, specyfikacje użytkowania i zmiany w konfiguracji, to kluczowy element każdej dokumentacji. Dzięki temu obecni użytkownicy będą mogli zobaczyć, jak słownictwo stale się rozwija i osiągać kolejne kamienie milowe, a także promować wykorzystanie słownictwa w względnie nowszych projektach. Pożądane efekty mojej kariery jako stażystki obejmują nie tylko sporządzenie praktycznego przewodnika z używaniem dotychczasowych komponentów, ale także opracowanie i opracowanie strony głównej (co pozwoliłoby na opracowanie zintegrowanej dokumentacji dla każdego z tych języków) z zakresu Słownictwa, Vue-Vocabulary i Fonts.
Plan projektu
Problem: dokumentacja jest jednym z głównych czynników decydujących o skuteczności określonej biblioteki open source. Główne pytanie, które zadają programiści podczas wybierania odpowiedniego stosu technologicznego do tworzenia aplikacji: „Czy biblioteka jest dobrze udokumentowana? Czy jest dobrze utrzymana? Czy jest to w pewnym stopniu obszerne w zakresie użycia i błędów?”. To właśnie pytania, które należy sobie zadać, omawiając pomysł projektu. Z punktu widzenia inżynierii oprogramowania:
Analiza wymagań: istnieje potrzeba opracowania zwięzłej i skonsolidowanej dokumentacji odpowiadającej naszym potrzebom. Brak dokumentacji negatywnie wpływa na przyszłe perspektywy aplikacji open source i jest zdecydowanie niezbędnym i nieistotnym elementem. Link do tych dokumentów powinien być atrakcyjną stroną główną, która w mgnieniu oka zacznie przyciągać uwagę odbiorców. Dokumentacja powinna być uporządkowana, aby zapewnić jej płynny przebieg.
Specyfikacje: w zależności od wymagań można określić specyfikacje. Treść tej dokumentacji można utworzyć na podstawie danych znajdujących się w witrynach CC Netlify, a także inspiracji pochodzących ze znanych dokumentów, takich jak semantic-ui, scikit-learn, numpy, bootstrap itp. Wynikiem tego zadania będzie wymagana strona docelowa i pełna dokumentacja.
Oto kilka ogólnych problemów związanych obecnie z słownicami, Vue-Vocabulary i czcionkami:
Dokumenty nie są dostępne, a nawet jeśli są, ich fragmenty są rozsiane po różnych witrynach internetowych. Użytkownicy, deweloperzy ani współtwórcy zewnętrzni nie będą mogli korzystać z naszej biblioteki.
Aby uzyskać dostęp do określonego komponentu i skopiować odpowiadający mu kod, trzeba kliknąć dodatkowe kliknięcia. Proste wyszukiwanie w Google np. „Karty komponent CC Vocabulary” nie zwróci oczekiwanych informacji. Opcja wyszukiwania w przewodnikach z dokumentacją znacznie poprawiłaby wygodę użytkowników.
Nieco bardziej szczegółowy opis poszczególnych komponentów, zawierający nieoczywiste szczegóły.
Brak opcji uruchomienia na żywo. Uruchomienie na żywo jest obsługiwane przez różne strony, takie jak JSFiddle, dzięki czemu programiści mogą poznać działanie komponentu bez uruchamiania całej aplikacji.
Rozwiązanie
Istnieje wiele możliwych rozwiązań. Przejdę jednak do kilku z nich, a w podsumowaniu przedstawię moje ostateczne rozwiązanie:
= Korzystanie z readthedocs readthedocs to dobrze znane rozwiązanie do tworzenia dokumentacji dla bibliotek open source. Podstawą tego narzędzia jest Sphinx – narzędzie do dokumentacji Pythona.
Zalety:
- Powszechnie uznawana forma generowania dokumentacji używana przez organizacje takie jak Ethereum (Solidity).
- Optymalnie uporządkowana dokumentacja.
- Bezpłatny hosting statyczny.
Wady:
- Brak absolutnej kontroli nad stylem.
= Sfinks
Zalety:
- Najpopularniejsze narzędzie Pythona do obsługi dokumentacji.
- Oferuje również obsługę wyszukiwania w dokumentacji.
- Domyślny kod CSS można zastąpić kodem niestandardowym; pewna kontrola nad kodem HTML za pomocą plików .rst.
Wady:
- Obejmuje kodowanie w Pythonie i zmienionym formacie tekstu (.rst), co będzie odchyleniem od sugerowanych języków projektu.
= Korzystanie z motywów Jekyll Motywy Jekyll są zintegrowane ze stronami na github. Istnieją też gotowe szablony, które można dostosować do naszych potrzeb.
Zalety:
- Gotowe motywy dokumentacji do wszystkich celów.
- Domyślne style CSS i style mogą być zastępowane ustawieniami niestandardowymi. Możesz też kontrolować kod HTML.
- Pobiera domyślny arkusz CSS Primer na potrzeby tworzenia stron.
- Łatwa integracja ze stronami GitHub.
Wady:
- Struktura dokumentacji może być nieodpowiednia.
=Używanie stron GitHub Standardowe strony github do tworzenia naszej witryny statycznej (HTML, CSS, JS).
Zalety:
- Pełna kontrola nad niemal wszystkimi kwestiami, których dotyczy problem.
- Maksymalna swoboda w decydowaniu o układzie, kolorach i stylach.
- Łatwe korzystanie z komponentów Słownictwa.
- Łatwe umieszczanie fragmentów kodu i linków do uruchamiania na żywo.
Wady:
- Może to być bardziej czasochłonne.
= Za pomocą Haroopada. Jest to alternatywne rozwiązanie w formacie Markdown.
Zalety:
- Wymaga minimalnej skomplikowanych działań przy kodowaniu.
- Należy skupić się na dopracowaniu dokumentacji.
Wady:
- Brak kontroli nad CSS.
- Pomoc ze strony społeczności może być najlepsza, ale nie zawsze.
- Może nie obsługiwać MDX.
= Korzystanie z Dokumentów MK Jest to alternatywne rozwiązanie w formacie Markdown.
Zalety:
- Wymaga minimalnego skomplikowanego kodowania (ponownie).
- Pisz więcej, mniej kodu.
Wady:
- Brak kontroli nad CSS.
- Pomoc społeczności może być niewystarczająca.
- Korzysta z języka Python; w dalszym ciągu może zaistnieć potrzeba uruchomienia instancji Amazon S3.
= Korzystanie z VueJS +StorybookJS To podejście jest powszechnie stosowane w Słowniczkach i powiązanych repozytoriach.
Zalety:
- Koncentrowanie się na technologiach, które gwarantują dobre działanie przy uwzględnieniu dotychczasowych doświadczeń w pracy
- Znajomość bazy kodu.
- Brak odpowiedniej technologii w tym pokoju.
Wady:
- Do tych samych celów mogą być też dostępne prostsze opcje.
Podsumowując, moim zdaniem najbardziej odpowiednie będzie podejście VueJS+Storybook (HTML,CSS,JS), ponieważ też jest ono dla mnie odpowiednie. Jednak oznacza to również, że nie będziemy całkowicie rezygnować z prac nad tą aplikacją. Można też dość łatwo użyć komponentów „CC-Vocabulars”. Jednak w oparciu o strukturę dokumentacji należy koniecznie uwzględnić sposób jej podziału na podtytuły. Zaimponowała mi witryna Semantic-UI (która korzysta z StoryBook) ze względu na minimalistyczny wygląd i możliwość wyboru, czego szuka użytkownik już po kilku kliknięciach. Oprócz interfejsu Semantic-UI przyjrzałam się też Material Design, Primer, Bootstrap, Carbon Design itp., które posłużyły mi jako przewodniki po stylizowaniu interfejsu i systemy projektowania w mojej pracy. Możemy też poszukać inspiracji w gotowej dokumentacji Jekyll.