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:
- Licencja Creative Commons
- Pisarz techniczny:
- nimishnb
- Nazwa projektu:
- Przewodnik po korzystaniu z słownictwa
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie projektu
Słownictwo ma ogromny potencjał, aby można było wykorzystać je jako podstawową bibliotekę komponentów UI przy tworzeniu witryn. Potrzebny jest solidny, ale przystępny dla laików przewodnik. Ważne informacje dla programistów, takie jak przewodniki po komponentach, specyfikacje użytkowania i poprawki konfiguracji, stanowią istotną część każdej dokumentacji. Dzięki temu obecni użytkownicy nie tylko zorientują się, w jaki sposób słownictwo stale się rozwija i osiąga kolejne etapy, ale także umożliwi wykorzystanie słownictwa w względnie nowszych projektach. Pożądanymi rezultatami mojej pracy jako stażysty jest nie tylko opracowanie praktycznego poradnika na temat korzystania z istniejących już komponentów, ale również zaprojektowanie i opracowanie strony głównej (prowadzącej do zintegrowanej dokumentacji dotyczącej każdej z nich) z zakresu Słownictwa, Słownictwa i Czcionek.
Plan projektu
Problem: dokumentacja jest jedną z głównych przyczyn określających skuteczność określonej biblioteki open source. Główne pytanie, które programiści zadają przy wyborze odpowiedniego stosu technologicznego do tworzenia aplikacji: „Czy biblioteka jest dobrze udokumentowana? Czy jest dobrze utrzymana? Czy usługa ta zapewnia znaczącą obsługę i obsługę błędów?”. To właśnie takie pytania należy sobie zadać, rozpatrując pomysły związane z projektem. Z perspektywy inżynierii oprogramowania:
Analiza wymagań: Dla naszych potrzeb od razu potrzebna jest zwięzła i skonsolidowana dokumentacja. Brak dokumentacji niekorzystnie wpływa na przyszłe perspektywy aplikacji open source i jest zdecydowanie niezbędnym i istotnym elementem. Linki do tych dokumentów powinny być atrakcyjne dla strony głównej, która pozwoli w mgnieniu oka zainteresować użytkowników. Dokumentacja powinna być dobrze zorganizowana, aby umożliwić jej płynne przejście.
Specyfikacje: W zależności od wymagań można określić specyfikacje. Zawartość dokumentacji można utworzyć z danych dostępnych na stronach internetowych CC oraz z 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 z Słownictwom, Słownictwem i Czcionkami:
Nie ma dokumentacji, a nawet jeśli niektóre z nich są rozsiane w różnych witrynach internetowych. Użytkownicy, deweloperzy ani współtwórcy z zewnątrz nie będą mogli korzystać z naszej biblioteki.
Aby uzyskać dostęp do określonego komponentu i skopiować odpowiadający mu kod, trzeba wykonać dodatkowe kliknięcia. Proste wyszukiwanie w Google np. „Składniki kart CC Słownictwo” nie zwróci oczekiwanych informacji. Opcja wyszukiwania w przewodnikach po dokumentacji znacznie poprawiłaby wygodę użytkowników.
Bardziej szczegółowy opis komponentów, który zawiera nieoczywiste szczegóły.
Brak opcji uruchomienia na żywo. Uruchomienie na żywo jest obsługiwane przez różne witryny, takie jak JSFiddle, dzięki czemu deweloperzy mogą się zapoznać z komponentem bez uruchamiania całej aplikacji.
Rozwiązanie
Istnieje wiele możliwych rozwiązań. Omówię jednak kilka z nich i przedstawię ostateczne rozwiązanie w części podsumowującej:
= Korzystanie z readthedocs readthedocs jest dobrze znanym rozwiązaniem do tworzenia dokumentacji bibliotek open source. Podstawą tego narzędzia jest Sphinx – narzędzie do dokumentacji Pythona.
Zalety:
- Powszechnie stosowana forma generowania dokumentacji, z której korzystają organizacje takie jak Ethereum (Solidity).
- Optymalnie uporządkowana dokumentacja.
- Bezpłatny hosting statyczny.
Wady:
- Brak absolutnej kontroli nad stylem.
= Użycie sfinksa Można też natywnie wykorzystać sfinksa w części dokumentacji. Ten sfinks zapewnia przydatne funkcje do wszystkich celów.
Zalety:
- Najpopularniejsze narzędzie do tworzenia dokumentacji w Pythonie.
- Udostępnia też obsługę wyszukiwania w dokumentacji.
- Domyślny kod CSS można zastąpić kodem niestandardowym, a w pewnym stopniu kontrolować kod HTML za pomocą plików .rst.
Wady:
- Wymaga kodowania w języku Python i zrestrukturyzowanego formatu tekstu (.rst), co będzie odbiegiem od sugerowanych języków używanych w projekcie.
= 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 zastosowań.
- Domyślne style CSS i style mogą być zastępowane ustawieniami niestandardowymi oraz możesz kontrolować kod HTML.
- Pobiera domyślny kod CSS aplikacji Primer do tworzenia stron.
- Łatwa integracja ze stronami GitHub.
Wady:
- Struktura dokumentacji może być nieodpowiednia.
=Używanie stron GitHub Standardowe strony github do tworzenia witryny statycznej (HTML, CSS, JS).
Zalety:
- Pełna kontrola nad prawie wszystkimi kwestiami, których dotyczy problem.
- Maksymalna swoboda wyboru układu, kolorów i stylów.
- Łatwe korzystanie z komponentów słownictwa.
- Łatwe umieszczanie fragmentów kodu i linków do uruchamiania na żywo.
Wady:
- Może to zająć więcej czasu.
Za pomocą Haroopada Zapewnia to alternatywne rozwiązanie w formacie Markdown.
Zalety:
- Wymagało to minimalnego wysiłku z kodowaniem.
- Należy skupić się na dopracowaniu dokumentacji.
Wady:
- Brak kontroli nad CSS.
- Wsparcie społeczności może być najlepsze, ale nie musi.
- Może nie obsługiwać MDX.
= Używanie dokumentów MK Jest to alternatywne rozwiązanie w formacie Markdown.
Zalety:
- Wiąże się to z minimalnym skomplikowanym kodowaniem (ponownie).
- Pisz więcej, pisz mniej kodu.
Wady:
- Brak kontroli nad CSS.
- Pomoc ze strony społeczności może być niewystarczająca.
- Korzysta z języka Python; w dalszym ciągu może pojawić się potrzeba uruchomienia instancji Amazon S3.
= Korzystanie z VueJS +StorybookJS To podejście jest powszechnie stosowane w Słownicy i jej pozostałych repozytoriach.
Zalety:
- Wspieranie technologii, które zgodnie z doświadczeniami z przeszłości gwarantuje, że będą działać dobrze.
- Znajomość bazy kodu.
- Brak odpowiedniej technologii na tym obszarze.
Wady:
- Do tych samych celów mogą być też dostępne prostsze opcje.
Podsumowując, wydaje mi się, że najbardziej odpowiednie wydaje się podejście oparte na VueJS+Storybook (HTML,CSS, JS), bo też mi to odpowiada. Oznacza to jednak również, że nie zamierzamy całkowicie odmówić w tworzeniu tej aplikacji. Użycie komponentów słów kluczowych w polu DW jest też proste. Jednak przy podejmowaniu decyzji o strukturze dokumentacji należy koniecznie wziąć pod uwagę sposób podziału treści na podtytuły. Zaimponowała mi strona Semantic-UI (z wykorzystaniem StoryBook), ponieważ ma minimalistyczny wygląd i już po kilku kliknięciach można łatwo zorientować się, czego potrzebuje. Poza interfejsem semantycznym zainteresowałem się też interfejsami Material Design, Primer, Bootstrap, Carbon Design itp., które posłużyły mi za wskazówki dotyczące stylu interfejsu i systemy projektowania interfejsu. Możemy też poszukać inspiracji w gotowej dokumentacji Jekylla.