Możesz mieć najlepszy projekt z otwartym kodem źródłowym, ale jeśli nie ma on dobrej dokumentacji, istnieje ryzyko, że nigdy nie odniesie sukcesu. Dobra dokumentacja w biurze pozwoli uniknąć zadawania tych samych pytań. Dokumentacja gwarantuje również, że ludzie mogą zrozumieć projekt, nawet jeśli kluczowi pracownicy opuszczą firmę lub zmienią się role. Żywe wytyczne pomogą zapewnić integralność danych.
Jeśli musisz napisać długi tekst, Markdown to doskonała alternatywa dla HTML. Czasami składni Markdown może być za mało. W takim przypadku możemy używać HTML wewnątrz niego. Na przykład, niestandardowe elementy. Dlatego, jeśli tworzysz system projektowania z natywnymi komponentami webowymi, łatwo je włączyć do tekstowej dokumentacji. Jeśli używasz React (lub jakiegokolwiek innego frameworka JSX, takiego jak Preact czy Vue), możesz zrobić to samo za pomocą MDX.
Ten artykuł to szeroki przegląd narzędzi do pisania dokumentacji i tworzenia wytycznych. Nie wszystkie narzędzia wymienione tutaj korzystają z MDX, ale jest on coraz częściej włączany w narzędzia dokumentacyjne.
Czym jest MDX?
Plik .mdx ma ten sam składnik co Markdown, ale pozwala na importowanie interaktywnych komponentów JSX i osadzanie ich w treści. Wsparcie komponentów Vue znajduje się w fazie alfa. Aby rozpocząć pracę z MDX, wystarczy zainstalować "Create React App". Istnieją wtyczki dla Next.js i Gatsby. Następna wersja Docusaurus (wersja 2) także będzie miała wbudowane wsparcie.
Pisanie dokumentacji z Docusaurus
Docusaurus został napisany przez Facebook. Używają go w każdym projekcie z otwartym kodem źródłowym poza React. Poza firmą korzysta z niego Redux, Prettier, Gulp i Babel.
Projekty, które używają Docusaurus.
Docusaurus można używać do pisania przez kogokolwiek dokumentacji, nie tylko do opisu front-endu. Ma pod maską React, ale nie trzeba mieć z nim styczności, aby go używać. Przekształca Twoje pliki Markdown, dodaje trochę magii i gotowa jest dobrze zorganizowana, sformatowana i czytelna dokumentacja z pięknym designem.
Na stronie Redux można zobaczyć standardowy szablon Docusaurus.
Strony stworzone za pomocą Docusaurus mogą również obejmować bloga opartego na Markdown. Do podświetlania składni od razu zainstalowano Prism.js. Mimo że Docusaurus pojawił się stosunkowo niedawno, został uznany za najlepsze narzędzie 2018 roku na StackShare.
Inne opcje tworzenia treści
Docusaurus został specjalnie zaprojektowany do tworzenia dokumentacji. Oczywiście istnieje milion i jeden sposób na stworzenie strony — możesz wdrożyć własne rozwiązanie w dowolnym języku, CMS lub skorzystać z generatora statycznych stron.
Na przykład dokumentacja dla React, system designu IBM, Apollo i Ghost CMS korzystają z Gatsby — to generator statycznych stron, który często jest używany do blogów. Jeśli pracujesz z Vue, VuePress będzie dobrym wyborem. Inną opcją jest użycie generatora napisanego w Pythonie — MkDocs. Jest to rozwiązanie otwarte i konfigurowane za pomocą jednego pliku YAML. GitBook również jest niezłym rozwiązaniem, ale jest bezpłatny tylko dla otwartych i niekomercyjnych zespołów. Można również po prostu przesyłać pliki markdown, korzystając z gita, i pracować z nimi w Githubie.
Dokumentowanie komponentów: Docz, Storybook i Styleguidist
Wytyczne, systemy designu, biblioteki komponentów — niezależnie od tego, jak je nazwiesz, stały się one ostatnio bardzo popularne. Pojawienie się komponentowych frameworków, takich jak React, oraz narzędzi wymienionych tutaj, pozwoliło przekształcić je z próżnościowych projektów w użyteczne narzędzia.
Storybook, Docz i Styleguidist robią to samo: wyświetlają interaktywne elementy i dokumentują ich API. Projekt może mieć dziesiątki, a może nawet setki komponentów — każdy z różnymi stanami i stylami. Jeśli chcesz, aby komponenty były używane wielokrotnie, ludzie muszą wiedzieć, że istnieją. Wystarczy zinwentaryzować komponenty. Wytyczne zapewniają łatwy do przeszukiwania przegląd wszystkich twoich komponentów. Pomaga to w utrzymaniu wizualnej spójności i unikaniu ponownej pracy.
Te narzędzia oferują wygodny sposób przeglądania różnych stanów. Może być trudno odtworzyć każde wystąpienie komponentu w kontekście rzeczywistej aplikacji. Zamiast klikać w rzeczywiste aplikacje, warto zaprojektować osobny komponent. Można modelować trudne do uchwycenia stany (na przykład stan ładowania).
Wraz z wizualną prezentacją różnych stanów oraz listą właściwości, często konieczne jest napisanie ogólnego opisu treści – uzasadnienia designu, przypadków użycia lub opisu wyników testów użytkowników. Markdown jest bardzo prosty do nauki – idealnie, gdyby wytyczne były wspólnym zasobem dla projektantów i deweloperów. Docz, Styleguidist oraz Storybook oferują możliwość łatwego łączenia Markdown z komponentami.
Docz
Docz obecnie działa tylko z React, ale są aktywne prace nad wsparciem dla Preact, Vue oraz komponentów webowych. Docz jest najnowszym z trzech narzędzi, ale na Githubie zdobył ponad 14 000 gwiazdek. Docz reprezentuje dwa komponenty — <Playground> i < Props >. Są one importowane i używane w plikach .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Możesz _pisać_ **markdown**
### Możesz importować i używać komponentów
Możesz owinąć swoje własne komponenty React za pomocą <Playground>, aby stworzyć odpowiednik wbudowanego CodePen lub CodeSandbox – czyli widzisz swój komponent i możesz go edytować.
<Props> pokaże wszystkie dostępne właściwości dla tego komponentu React, wartości domyślne oraz to, czy właściwość jest wymagana.
<Props of={Button} />Osobiście uważam, że to podejście oparte na MDX jest najprostsze do zrozumienia i najłatwiejsze do pracy.
Jeśli jesteś fanem generatora statycznych stron Gatsby, Docz oferuje doskonałą integrację.
Styleguidist
Podobnie jak w Docz, przykłady są pisane przy użyciu składni Markdown. Styleguidist używa bloków kodu Markdown (potrójne cudzysłowy) w zwykłych plikach .md plikach, a nie w MDX.
```js
Bloki kodu w Markdown zazwyczaj pokazują po prostu kod. Przy użyciu Styleguidist każdy blok kodu z oznaczeniem języka js, jsx lub javascript będzie wyświetlany jako komponent React. Jak w Docz, kod jest edytowalny – możesz zmieniać właściwości i od razu widzieć wyniki.
Styleguidist automatycznie stworzy tabelę właściwości z deklaracji PropTypes, Flow lub Typescript.
Styleguidist obecnie wspiera React i Vue.
Storybook
Storybook pozycjonuje się jako „środowisko rozwoju komponentów UI”. Zamiast pisać przykłady komponentów wewnątrz plików Markdown lub MDX, piszesz historii wewnątrz plików Javascript. Historia dokumentują konkretne stany komponentu. Na przykład, komponent może mieć historie dla stanu ładowania i wyłączonego stanu (wyłączone).
storiesOf('Button', module)
.add('wyłączone', () => (
))Storybook jest znacznie bardziej skomplikowany niż Styleguidist i Docz. Mimo to jest to najpopularniejsza opcja, projekt na GitHubie ma ponad 36 000 gwiazdek. To projekt z otwartym kodem źródłowym, w którym bierze udział 657 uczestników oraz wspierają go pracownicy. Używa go Airbnb, Algolia, Atlassian, Lyft i Salesforce. Storybook wspiera więcej frameworków niż konkurencja — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte oraz zwykły HTML.
W przyszłej wersji znajdą się funkcje z Docz i wprowadzany jest MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nowe funkcje Storybooka będą stopniowo wprowadzane w ciągu najbliższych kilku miesięcy i prawdopodobnie będzie to duży krok naprzód.
Podsumowanie
Zalety bibliotek wzorców są wychwalane w milionach artykułów na Medium. Kiedy wszystko jest zrobione dobrze, ułatwiają tworzenie pokrewnych produktów i utrzymanie tożsamości. Oczywiście, żaden z tych narzędzi nie pomoże magicznie stworzyć systemu projektowego. Wymaga to starannego zaprojektowania i CSS. Ale kiedy nadchodzi czas, aby udostępnić system projektowy całej firmie, Docz, Storybook i Styleguidist są świetnymi opcjami.
Od tłumacza. To moje pierwsze doświadczenie na Habrze. Jeśli zauważyłeś jakieś nieścisłości lub masz sugestie dotyczące poprawy artykułu — pisz do mnie prywatnie.
Źródło: habr.com
