Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- Creative Commons
- Specjalista ds. technicznych:
- nimishnb
- Nazwa projektu:
- Przewodnik po korzystaniu z terminów
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie projektu
Vocabulary ma ogromny potencjał jako główna biblioteka komponentów interfejsu użytkownika do tworzenia witryn. Potrzebuje ono solidnego, a jednocześnie przystępnego dla laików przewodnika. Ważne informacje dla programistów, takie jak przewodniki po komponentach, specyfikacje użycia i ustawienia konfiguracji, stanowią istotną część dokumentacji. W ten sposób nie tylko zachęca to obecnych użytkowników do odkrywania słownictwa i osiągania kolejnych kamieni milowych, ale będzie też promować użycie Słownictwa w stosunkowo nowszych projektach. Osiągnięcie zamierzonych celów w trakcie stażu będzie wymagało nie tylko stworzenia praktycznego przewodnika po korzystaniu z dotychczasowych komponentów, ale też zaprojektowania i opracowania strony głównej (z integrowaną dokumentacją dla każdego z tych komponentów) dla Vocabulary, Vue-Vocabulary i Fonts.
Plan projektu
Problem: dokumentacja jest jednym z głównych czynników decydujących o tym, jak popularna będzie dana biblioteka open source. Główne pytanie, które programiści biorą pod uwagę, wybierając odpowiedni stos technologiczny do tworzenia aplikacji, brzmi: „Czy biblioteka jest dobrze udokumentowana? Czy jest dobrze utrzymany? Czy jest ono wystarczająco rozbudowane i czy obsługuje błędy? To właśnie te pytania powinniśmy sobie zadać, gdy rozważamy ten pomysł na projekt. Z perspektywy inżynierii oprogramowania:
Analiza wymagań: zawsze potrzebujemy zwięzłej i skonsolidowanej dokumentacji. Brak dokumentacji negatywnie wpływa na przyszłość aplikacji open source i jest zdecydowanie istotnym i istotnym elementem. Linki do tych dokumentów powinny być atrakcyjną stroną główną, która w mgnieniu oka wzbudzi zainteresowanie użytkowników. Dokumentacja powinna być dobrze uporządkowana, aby można było ją łatwo przeglądać.
Specyfikacje: w zależności od wymagań możesz określić specyfikacje. Treści w dokumentacji mogą być tworzone na podstawie danych obecnych w witrynach CC netlify oraz inspiracji z dobrze znanych dokumentacji, 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 Vocabulary, Vue-Vocabulary i Fonts:
Brakuje dokumentacji, a nawet jeśli jest ona dostępna, jej części są rozproszone po różnych stronach Netlify. Nie oznacza to jednak, że użytkownicy, deweloperzy i zewnętrzni współtwórcy mogą korzystać z naszej biblioteki.
Aby dostać się do określonego komponentu i skopiować jego kod, trzeba wykonać dodatkowe kliknięcia. Proste wyszukiwanie w Google pod hasłem „Składnik kart Słownictwo CC” nie zwraca pożądanych informacji. Opcja wyszukiwania w dokumentacji znacznie poprawiłaby UX.
nieco bardziej szczegółowy opis tekstowy komponentów, zawierający nieoczywiste informacje;
Brak opcji uruchomienia kampanii na żywo. Testowanie na żywo jest obsługiwane przez różne witryny, takie jak JSFiddle, co pozwala deweloperom poznać komponent bez konieczności uruchamiania całej aplikacji.
Rozwiązanie
Jest wiele możliwych rozwiązań. W tym artykule omówię kilka z nich, a w podsumowaniu przedstawię moje ostateczne rozwiązanie:
= Korzystanie z readthedocs readthedocs to znane rozwiązanie do tworzenia dokumentacji dla bibliotek open source. Bazuje na Sphinx – narzędziu do dokumentacji języka Python.
Zalety:
- Powszechnie akceptowana forma generowania dokumentacji, używana przez organizacje takie jak Ethereum (Solidity).
- Optymalnie ustrukturyzowana dokumentacja.
- Bezpłatny hosting statyczny.
Wady:
- Brak pełnej kontroli nad stylizacją.
= Korzystanie z Sphinxa W części dotyczącej dokumentacji możemy też domyślnie użyć Sphinxa, który oferuje dobre funkcje do wszystkich naszych celów.
Zalety:
- Najpopularniejsze narzędzie Pythona do dokumentacji.
- Umożliwia też wyszukiwanie dokumentacji.
- Domyślny kod CSS można zastąpić kodem niestandardowym. Niektóre elementy kontrolują kod HTML za pomocą plików .rst.
Wady:
- Polega ono na pisaniu kodu w Pythonie i formatowaniu tekstu (.rst), co odbiega od sugerowanych języków projektu.
= Korzystanie z motywów Jekyll Motywy Jekyll są zintegrowane ze stronami github i istnieją już szablony, które można dostosować do własnych potrzeb.
Zalety:
- Gotowe motywy dokumentacji do wszystkich zastosowań.
- Domyślny kod CSS i style można zastąpić niestandardowymi, a także kontrolować kod HTML.
- Pobiera domyślny CSS Primer do tworzenia stron.
- Łatwa integracja ze stronami GitHub.
Wady:
- Może nie zapewniać najlepszej struktury dokumentacji.
=Korzystanie ze stron GitHub Standardowe strony GitHub do tworzenia witryn statycznych (HTML, CSS, JS).
Zalety:
- Pełna kontrola nad prawie wszystkimi kwestiami.
- Maksymalna elastyczność w określaniu układu, kolorów i stylów.
- Łatwe korzystanie z komponentów słownictwa.
- Łatwe umieszczanie fragmentów kodu i linków do bezpośredniego uruchamiania.
Wady:
- Może to być bardziej czasochłonne.
= Używanie Haroopad To daje alternatywę dla markdown.
Zalety:
- Wymaga minimalnego skomplikowania w kodowaniu.
- Głównym celem będzie stworzenie perfekcyjnej dokumentacji.
Wady:
- Brak kontroli nad usługą porównywania cen.
- Może nie mieć najlepszego wsparcia społeczności.
- Może nie obsługiwać formatu MDX.
= Korzystanie z MKDocs To daje alternatywę dla markdowna.
Zalety:
- Wymaga to minimalnego kodowania (ponownie).
- Pisanie większej ilości kodu z mniejszą ilością kodu.
Wady:
- Brak kontroli nad usługą porównywania cen.
- Może nie mieć najlepszego wsparcia społeczności.
- Używa Pythona; może być konieczne uruchomienie instancji Amazon S3.
= Wykorzystanie VueJS +StorybookJS Ta metoda jest powszechnie stosowana w VueJS i jej repozytoriach partnerskich.
Zalety:
- Używanie technologii, które działają bez zarzutu, ponieważ są sprawdzone.
- znajomość bazy kodu;
- W tej przestrzeni nie ma odpowiedniej technologii.
Wady:
- Do tych samych celów dostępne są też prostsze opcje.
Podsumowując, uważam, że podejście oparte na VueJS + Storybook (HTML, CSS, JS) wydaje się najbardziej odpowiednie, ponieważ jest mi też wygodne. Oznacza to jednak, że nie będziemy się specjalnie wysilać, aby rozwijać tę aplikację. Użycie komponentów CC-Vocabulary jest też dość proste. Jednak aby określić strukturę dokumentacji, należy wziąć pod uwagę sposób podziału treści na podnagłówki w dokumentacji readthedocs. Jestem pod wrażeniem strony Semantic-UI (która korzysta z StoryBook), ponieważ ma minimalistyczny wygląd i można łatwo dowiedzieć się, czego się chce, po zaledwie kilku kliknięciach. Oprócz Semantic-UI sprawdziłem też Material Design, Primer, Bootstrap, Carbon Design itp., aby wykorzystać je jako przewodniki po stylach interfejsu i systemy projektowania. Możemy też poszukać inspiracji w gotowych motywach do dokumentacji Jekylla.