VuePress: Prosta dokumentacja

Jeśli chodzi o każdy projekt, który wymaga interakcji z użytkownikiem (np. użytkownicy końcowi, opiekunowie itp.), istnieje jeden krytyczny czynnik, który decyduje o sukcesie lub porażce: dobra dokumentacja. Odnosi się to niezależnie od tego, jak mały lub duży jest Twój projekt. W końcu, poza zapewnieniem indywidualnego wsparcia dla twojego projektu, dokumentacja jest pierwszą linią obrony dla użytkowników, którzy próbują rozwiązać problem. I czy ci się to podoba, czy nie, nigdy nie usłyszysz od użytkowników, którzy poddają się, gdy nie są w stanie rozwiązać swojego problemu z powodu nieodpowiedniej dokumentacji.

Wyzwania związane z tworzeniem dobrej dokumentacji

Jeśli chodzi o pisanie dobrej dokumentacji, zespoły często napotykają cztery powtarzające się problemy:

1. Dokumentacja jest często nieaktualna.
   Chociaż brak dokumentacji projektu może być frustrującym doświadczeniem, prawdopodobnie gorzej jest mieć nieaktualną dokumentację. W końcu celem posiadania dokumentacji jest dostarczenie użytkownikom oficjalnej wiedzy, na której mogą polegać. Kiedy jest nieaktualny, użytkownicy marnują czas i ostatecznie tracą zaufanie do Twojego produktu.
   
   Głównym powodem, dla którego dokumentacja staje się nieaktualna, jest to, że utrzymywanie dokumentacji jest oddzielone od zmian w kodzie . Bez inwestowania znacznej ilości czasu i energii może to być trudne do rozwiązania, ponieważ:
   
   1. Dokumentacja zwykle znajduje się w serwisie zewnętrznym, takim jak Confluence lub Wiki,
   2. Deweloperzy są zazwyczaj bardziej zainteresowani pisaniem kodu niż dokumentacją.
2. Użytkownicy nie są w stanie w łatwy sposób przekazać opinii.
   Bez względu na to, jak dobra jest Twoja dokumentacja, ostatecznie nie ma ona sensu bez testowania jej z prawdziwymi użytkownikami, którzy mogą przekazać opinię. Jak wspomniano wcześniej, powszechnym uprzedzeniem przy ocenie skuteczności takich rzeczy jak dokumentacja jest nieuwzględnianie użytkowników, którzy nie byli w stanie rozwiązać swoich problemów i zrezygnowali. Ponieważ żaden zespół nigdy nie byłby w stanie wyjaśnić każdego scenariusza, w jaki użytkownicy mogą korzystać z Twojego produktu, użytkownicy muszą mieć łatwy i niezawodny sposób przekazywania opinii.
3. Dokumentacja jest często pisana przez zaawansowanych użytkowników dla zaawansowanych użytkowników.
   Wadą korzystania ze standardowych narzędzi, takich jak wiki lub pliki README, jest to, że często obsługują one tylko określoną grupę użytkowników, którzy często mają wcześniejszą wiedzę na temat biblioteki i/lub stosu technologii. W rezultacie poruszanie się po przestrzeni i znajdowanie tego, czego potrzebują, jest dla nich dość proste. Jednak nowi użytkownicy nie mają tej wcześniejszej wiedzy i dlatego często wymagają znacznie bardziej wciągającego doświadczenia, aby ich zaangażować.
   
   Przykłady tego obejmują:
   
   • Dobrze zaprojektowana strona internetowa,
   • Możliwość wyszukiwania,
   • Nawigacja boczna z przewodnikiem,
   • Łatwe do zidentyfikowania metainformacje (tj. data ostatniej aktualizacji),
   • Wciągająca treść, która wykracza poza ścianę tekstu, która jest trudna do zrozumienia.
4. Słaba infrastruktura utrudniająca utrzymanie dokumentacji.
   Jakby pisanie dobrej dokumentacji zrozumiałej dla użytkowników nie było wystarczająco trudne, łatwość, z jaką programista może pisać i/lub utrzymywać dokumentację, ma kluczowe znaczenie dla jej długoterminowej żywotności. Tak więc dla każdej dodatkowej bariery, z którą programiści muszą się zmierzyć, aby pisać i/lub utrzymywać dokumentację, tym bardziej prawdopodobne jest, że ostatecznie zawiedzie. W rezultacie bardzo ważne jest, aby doświadczenie tworzenia i obsługi dokumentacji było tak płynne i angażujące, jak to tylko możliwe.

Gdyby tylko istniało narzędzie, które mogłoby zrobić to wszystko za nas…

Wejdź do VuePress

Kiedy po raz pierwszy słyszymy o VuePress, można pokusić się o odgadnięcie, że jest to połączenie Vue.js i WordPressa. Zamiast tego powinieneś pomyśleć o VuePress jako:

Vue.js + prasa drukarska

Ponieważ kiedy wszystko jest powiedziane i zrobione, VuePress jest statycznym generatorem witryn!

Niektórzy z was mogą myśleć: „Czekaj. Kolejny generator stron statycznych? O co tyle szumu?"

Chociaż istnieje wiele narzędzi, które są generatorami stron statycznych, VuePress wyróżnia się spośród innych z jednego powodu: jego główną dyrektywą jest ułatwienie programistom tworzenia i utrzymywania doskonałej dokumentacji dla ich projektów.

Dlaczego VuePress jest tak potężny w tworzeniu dokumentacji?

Odpowiedź jest prosta. Został zaprojektowany z myślą o jednym celu: pomóc programistom w tworzeniu wspaniałych witryn z dokumentacją przy jednoczesnym zachowaniu przyjemnego doświadczenia związanego z pisaniem. Oznacza to, że zapewnia programistom ramy umożliwiające:

• Twórz piękne strony z dokumentacją,
• Przyjdź z gotowymi funkcjami niezbędnymi dla wszystkich witryn z dokumentacją,
• Zoptymalizuj środowisko tworzenia, aby było tak proste, jak aktualizacja pliku Markdown.

VuePress może współistnieć z istniejącą bazą kodów

To jeden z głównych powodów, dla których gorąco go polecam. Jeśli chodzi o prowadzenie dokumentacji, jednym ze sposobów zagwarantowania, że ​​stanie się ona nieaktualna, jest utrudnienie programistom aktualizowania dokumentacji podczas pisania kodu. Jeśli utrudnisz tworzenie, zmuszając programistów do aktualizowania rzeczy w dwóch różnych miejscach, spowoduje to wiele tarcia i często spowoduje, że dokumentacja zostanie odłożona na bok. Jest to często obserwowane, gdy programiści muszą utrzymywać narzędzie stron trzecich, takie jak wiki, oprócz samej bazy kodu.

Ponieważ jest to statyczny generator witryn, oznacza to, że może znajdować się w tym samym repozytorium, co Twój kod.

Jak widać w tej przykładowej strukturze aplikacji sieci Web, Twój kod będzie normalnie znajdował się w katalogu src , ale po prostu miałbyś katalog docs , który zawierałby całą dokumentację. Oznacza to, że czerpiesz korzyści z:

• Cała dokumentacja jest teraz kontrolowana pod kątem wersji;
• Pull request może teraz zawierać zarówno dokumentację, jak i zmiany w kodzie;
• Tworzenie osobnych skryptów do jednoczesnego uruchamiania lokalnych instancji Twojego kodu i dokumentów;
• Użyj potoków kompilacji, aby określić, czy nowe wdrożenia witryny dokumentacji są zsynchronizowane z wdrożeniami kodu, czy nie.

Domyślny motyw jest dostarczany ze standardową konfiguracją

Pisanie dokumentacji jest wystarczająco trudne, więc VuePress odciąża wiele decyzji, które normalnie trzeba podjąć, i ma kilka wbudowanych ustawień domyślnych, które ułatwiają tworzenie:

• Pisanie treści odbywa się głównie za pomocą Markdown.
  Oznacza to, że możesz wykorzystać swoją dotychczasową wiedzę na temat składni Markdown do stylizacji i formatowania tekstu.

• Podświetlanie składni kodu.
  Gdybyś sam budował witrynę, musiałbyś zmagać się z bibliotekami podświetlania składni kolorami. Ale masz szczęście, ponieważ możesz dodawać bloki kodu w VuePress, ponieważ wszystko jest gotowe do pracy przy zerowej konfiguracji.

• Pierwsza sprawa przy definiowaniu metadanych na poziomie strony.
  Nawet jeśli tworzysz w pliku Markdown, możesz użyć frontu (takiego jak YAML, JSON lub TOML) do zdefiniowania metadanych dla swojej strony, aby jeszcze bardziej ułatwić zarządzanie treścią!

 --- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---

• Niestandardowe kontenery Markdown.
  Jeśli nie wiesz, Markdown ma rozszerzenia, które dodają jeszcze bardziej przydatne skróty do tworzenia pięknych komponentów interfejsu użytkownika, takich jak niestandardowe kontenery. A ponieważ są tak przydatne w dokumentacji, VuePress już go skonfigurował, abyś mógł z niego korzystać od razu po wyjęciu z pudełka:

Wbudowana funkcja wyszukiwania

Spojrzmy prawdzie w oczy. Bez względu na to, ile czasu spędzimy na pisaniu świetnej dokumentacji, ostatecznie okaże się to bezużyteczne, jeśli użytkownicy nie będą mogli jej znaleźć. Istnieją na ogół dwa podejścia do tego:

1. Poczekaj, aż roboty wyszukiwarek powoli indeksują Twoją witrynę w nadziei, że pewnego dnia Twoi użytkownicy będą mogli znaleźć odpowiednią stronę w Twojej witrynie. Nie jest to świetne rozwiązanie.
2. Utwórz własną funkcję wyszukiwania, ale może to być trudne do zaimplementowania w przypadku witryn statycznych, ponieważ po stronie serwera nie jest uruchomiony kod do tworzenia indeksów wyszukiwania i wykonywania wyszukiwań. Nie wspominając o tym, że zajmuje to czas opracowywania z dala od samego produktu. Więc to też nie jest świetne.

Na szczęście dla nas VuePress jest tutaj, aby ponownie uratować dzień!

VuePress ma wbudowaną funkcję wyszukiwania, która generuje własną „wyszukiwarkę” — dobrze to przeczytałeś. Bez dodatkowej konfiguracji lub konfiguracji bazy danych, VuePress jest skonfigurowany tak, aby zeskrobać całe dokumenty, aby wygenerować prostą wyszukiwarkę, która wyświetli wszystkie Twoje h1 i h2 użytkownikowi.

Niektórzy z was mogą myśleć:

„A co, jeśli potrzebuję czegoś, co zapewni indeksowanie niższego poziomu do wyszukiwania?”

Cóż, VuePress również Cię tam obejmuje, ponieważ został zaprojektowany tak, aby łatwo zintegrować się z Algolia DocSearch, który może zapewnić Ci tę funkcjonalność za darmo, jeśli spełniasz ich wymagania:

Nawigacja po pasku bocznym jest tak prosta, jak włączanie lub wyłączanie funkcji

Każdy, kto kiedykolwiek był odpowiedzialny za zarządzanie treścią, wie, jak skomplikowane może być zbudowanie paska bocznego z zagnieżdżonymi elementami, a następnie śledzenie pozycji czytnika podczas przewijania w dół. Po co więc spędzać na tym czas, skoro można pisać lepsze dokumenty? W VuePress pasek boczny jest tak prosty, jak przełączanie się na przednią część strony:

Automatyczne generowanie ważnych metadanych, które są często pomijane

Jedną z najbardziej frustrujących rzeczy, z jakimi może się spotkać użytkownik, jest nieaktualna dokumentacja. Gdy użytkownik postępuje zgodnie z instrukcjami i ma problem ze zrozumieniem, dlaczego coś nie działa, możliwość łatwego znalezienia daty ostatniej aktualizacji może być niezwykle przydatna zarówno dla użytkownika, jak i opiekunów projektu.

Dzięki prostej konfiguracji VuePress może zapewnić automatyczne wyświetlanie daty ostatniej aktualizacji na stronie, dzięki czemu użytkownicy zawsze wiedzą, kiedy ostatnia aktualizacja została zaktualizowana.

Co więcej, przy odrobinie konfiguracji, VuePress sprawia, że ​​użytkownikom niezwykle łatwo jest współtworzyć Twoje dokumenty, automatycznie generując link na dole każdej strony, który umożliwia użytkownikom łatwe tworzenie żądań ściągnięcia do Twoich dokumentów.

Nie ma nic prostszego dla Twoich użytkowników.

Wdrożenie w dowolnej statycznej witrynie hostingowej

Ponieważ VuePress jest w swojej istocie generatorem statycznych witryn, oznacza to, że możesz go wdrożyć na dowolnej popularnej platformie hostingowej, takiej jak:

• Netlifikuj
• Strony GitHub
• Strony GitLab
• Heroku
• Ale już

Wszystko, co musisz zrobić, aby zbudować witrynę, to uruchomić vuepress build {{ docsDir }} z miejscem, w którym znajduje się Twój katalog, a będziesz mieć wszystko, czego potrzebujesz, aby wdrożyć go na żywo w sieci!

Uwaga : Aby uzyskać bardziej szczegółowe instrukcje, jak to zrobić, zapoznaj się z oficjalnymi przewodnikami wdrażania dla VuePress.

Wykorzystanie Vue w Twoim pliku Markdown

Wiem wiem. Możemy użyć Vue.js w naszym Markdown?! Tak, dobrze to przeczytałeś! Chociaż jest to technicznie opcjonalne, jest to prawdopodobnie jeden z najbardziej ekscytujących aspektów VuePress, ponieważ pozwala ulepszyć zawartość Markdown, jak nigdy wcześniej.

Zdefiniuj powtarzalne dane w jednym miejscu i zaktualizuj je wszędzie dzięki interpolacji

W poniższym przykładzie zobaczysz krótki przykład wykorzystania zmiennych lokalnych (takich jak te zdefiniowane we frontmatter), a także zdefiniowanych globalnie (takich jak tytuł witryny):

 --- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!

Użyj komponentów Vue w ramach Markdown

Po przeczytaniu tego, dam ci chwilę na zebranie się, ale tak, żywe komponenty Vue z pełną instancją Vue mogą być twoje do wzięcia, jeśli chcesz! Konfiguracja zajmie trochę więcej pracy, ale należy się tego spodziewać, ponieważ tworzysz niestandardową zawartość, która będzie działać w Twojej dokumentacji.

Oto krótki przykład tego, jak składnik Counter wyglądałby w pliku Markdown:

Jest to prawdopodobnie najpotężniejsza część dostosowywania dostępna w dokumentacji, ponieważ oznacza to, że masz teraz swobodę tworzenia niestandardowych treści wykraczającą daleko poza możliwości standardowego Markdowna. Więc niezależnie od tego, czy jest to prezentacja, czy jakiś interaktywny kod, pomysły są nieograniczone!

Następne kroki

Jeśli chcesz stworzyć piękną witrynę z dokumentacją, aby Twoi użytkownicy mogli nauczyć się, jak korzystać z Twojego produktu, nie ma nic prostszego niż VuePress. I chociaż łatwo można założyć, że VuePress powinien być używany tylko przez projekty korzystające z Vue.js, nie może to być dalsze od prawdy. Oto tylko kilka przykładów różnych typów projektów wykorzystujących VuePress w swoich witrynach z dokumentacją:

• Craft CMS
• UmiJS (który jest zbudowany dla React)
• openHAB
• Paw

Podsumowując, niezależnie od tego, czy korzystasz z VuePress, czy nie, mam nadzieję, że pomogło Ci to zainspirować Cię do stworzenia lepszej dokumentacji dla Twoich użytkowników.

Dalsze zasoby

Jest wiele fajnych rzeczy, których nie omówiłem w tym artykule (np. motywy, blogowanie itp.), ale jeśli chcesz dowiedzieć się więcej, sprawdź te zasoby:

• Oficjalna dokumentacja VuePress
• Wyselekcjonowana lista zasobów związanych z VuePress
• Galeria VuePress
• VuePress Blog Boilerplate