Możesz mieć lepszy projekt open source, ale jeśli nie ma dobrej dokumentacji, są szanse, że nigdy nie wystartuje. W biurze dobra dokumentacja uchroni Cię przed ciągłym odpowiadaniem na te same pytania. Dokumentacja zapewnia również, że ludzie mogą zrozumieć projekt, jeśli kluczowi pracownicy opuszczą firmę lub zmienią się role. Wytyczne na żywo pomagają zapewnić integralność danych.
Jeśli potrzebujesz napisać długi tekst, Markdown jest świetną alternatywą dla HTML. Czasami składnia Markdown nie wystarcza. W takim przypadku możemy użyć w nim kodu HTML. Na przykład niestandardowe elementy. Dlatego jeśli budujesz system projektowy z natywnymi komponentami internetowymi, łatwo jest dołączyć je do dokumentacji tekstowej. Jeśli używasz React (lub dowolnego innego frameworka JSX, takiego jak Preact lub Vue), możesz zrobić to samo z MDX.
Ten artykuł jest obszernym przeglądem narzędzi do pisania dokumentacji i tworzenia wytycznych. Nie wszystkie wymienione tutaj narzędzia używają MDX, ale coraz częściej jest on dołączany do narzędzi do dokumentacji.
Co to jest MDX?
plik .mdx ma taką samą składnię jak Markdown, ale umożliwia importowanie interaktywnych komponentów JSX i osadzenie ich w treści. Obsługa komponentów Vue jest w wersji alfa. Aby rozpocząć pracę z MDX wystarczy zainstalować "Create React App". Istnieją wtyczki dla Next.js i Gatsby. Następna wersja Docusaurus (wersja 2) również będzie miała wbudowaną obsługę.
Pisanie dokumentacji za pomocą Docusaurusa
Dokuzaur napisał na Facebooku. Używają go w każdym projekcie open source z wyjątkiem React. Poza firmą używają go Redux, Prettier, Gulp i Babel.
Projekty wykorzystujące Docusaurus.
Docusaurus może być używany do pisania dowolny dokumentacji, a nie tylko do opisu frontendu. Pod maską ma Reacta, ale nie trzeba go znać, żeby z niego korzystać. Wystarczy Twoje pliki Markdown, szczypta magii i dobrze ustrukturyzowana, sformatowana i czytelna dokumentacja o pięknym wyglądzie jest gotowa.
Możesz zobaczyć domyślny szablon Docusaurus na stronie Redux.
Witryny zbudowane za pomocą Docusaurus mogą również zawierać blog oparty na Markdown. Do podświetlania składni Prism.js jest natychmiast dołączany. Pomimo tego, że Docusaurus pojawił się stosunkowo niedawno, został uznany za najlepsze narzędzie 2018 roku na StackShare.
Inne opcje tworzenia treści
Docusaurus jest specjalnie zaprojektowany do tworzenia dokumentacji. Oczywiście istnieje milion sposobów na stworzenie strony internetowej - możesz wdrożyć własne rozwiązanie w dowolnym języku, CMS lub skorzystać z generatora statycznych stron.
Na przykład dokumentacja React, systemu projektowego IBM, Apollo i Ghost CMS używa Gatsby, statycznego generatora witryn często używanego w blogach. Jeśli pracujesz z Vue, VuePress jest dla Ciebie dobrą opcją. Inną opcją jest użycie generatora napisanego w Pythonie - MkDocs. Jest otwarty i skonfigurowany za pomocą jednego pliku YAML. GitBook jest również dobrą opcją, ale jest bezpłatny tylko dla otwartych i niekomercyjnych zespołów. Możesz także po prostu przesłać pliki mardown za pomocą git i pracować z nimi w Github.
Dokumentacja komponentów: Docz, Storybook i Styleguidist
Wytyczne, projekt systemu, biblioteki komponentów, jakkolwiek chcesz je nazwać, stały się ostatnio bardzo popularne. Pojawienie się frameworków komponentowych, takich jak React i wspomnianych tutaj narzędzi, umożliwiło przekształcenie ich z próżnych projektów w użyteczne narzędzia.
Storybook, Docz i Styleguidist robią to samo: wyświetlają interaktywne elementy i dokumentują swoje API. Projekt może zawierać dziesiątki, a nawet setki komponentów, z których każdy ma inny stan i styl. Jeśli chcesz, aby komponenty były ponownie używane, ludzie muszą wiedzieć, że one istnieją. W tym celu wystarczy skatalogować komponenty. Wytyczne zapewniają łatwy do wyszukania przegląd wszystkich komponentów. Pomaga to zachować spójność wizualną i uniknąć powtarzalności pracy.
Narzędzia te zapewniają wygodny sposób przeglądania różnych stanów. Odtworzenie każdego stanu komponentu w kontekście rzeczywistej aplikacji może być trudne. Zamiast klikać w samą aplikację, warto opracować osobny komponent. Możliwe jest modelowanie trudno dostępnych stanów (np. stan ładowania).
Wraz z wizualną demonstracją różnych stanów i listą właściwości często konieczne jest napisanie ogólnego opisu zawartości - uzasadnień projektowych, przypadków użycia, czy opisu wyników testów użytkowników. Markdown jest bardzo łatwy do nauczenia – najlepiej byłoby, gdyby wytyczne były wspólnym zasobem dla projektantów i programistów. Docz, Styleguidist i Storybook oferują sposób na łatwe łączenie Markdown z komponentami.
Docz
Obecnie Docz współpracuje tylko z React, ale aktywnie pracuje nad wsparciem dla Preact, Vue i komponentów internetowych. Docz jest najnowszym z trzech narzędzi, ale udało mu się zebrać ponad 14 000 gwiazdek na Githubie. Docz wprowadza dwa komponenty − <Playground> и < Props >. Są importowane i używane w plikach .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Możesz opakować własne komponenty React <Playground>stworzyć odpowiednik wbudowanego CodePen lub CodeSandbox - czyli widzisz swój komponent i możesz go edytować.
<Playground>
<Button>click</Button>
</Playground><Props> pokaże wszystkie dostępne właściwości dla danego komponentu React, wartości domyślne oraz czy właściwość jest wymagana.
<Props of={Button} />Osobiście uważam, że to podejście oparte na MDX jest najłatwiejsze do zrozumienia i najłatwiejsze w użyciu.
Jeśli jesteś fanem statycznego generatora witryn Gatsby'ego, Docz oferuje świetne integracje.
przewodnik stylu
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 plików, a nie w MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Bloki kodu w Markdown zwykle pokazują tylko kod. Podczas korzystania ze Styleguidist dowolny blok kodu ze znacznikiem języka js, jsx lub javascript będzie renderowany jako komponent React. Podobnie jak Docz, kod jest edytowalny - możesz zmienić właściwości i natychmiast zobaczyć wynik.
Styleguidist automatycznie utworzy arkusz właściwości z deklaracji PropTypes, Flow lub TypeScript.
Styleguidist obsługuje teraz React i Vue.
Storybook
Storybook określa się jako „środowisko programistyczne komponentów interfejsu użytkownika”. Zamiast pisać przykłady komponentów w plikach Markdown lub MDX, piszesz Historie wewnątrz plików JavaScript. Historia udokumentować określony stan komponentu. Na przykład składnik może mieć historię stanu ładowania i stanu wyłączenia (niepełnosprawny).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook jest znacznie bardziej złożony niż Styleguidist i Docz. Ale jednocześnie jest to najpopularniejsza opcja, na Github projekt ma ponad 36 000 gwiazdek. Jest to projekt typu open source z 657 współpracownikami i personelem towarzyszącym. Korzystają z niego Airbnb, Algolia, Atlassian, Lyft i Salesforce. Storybook obsługuje więcej frameworków niż konkurencja - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte i zwykły HTML.
W przyszłej wersji pojawią się żetony firmy 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 Storybook będą wprowadzane stopniowo w ciągu najbliższych kilku miesięcy i wygląda na to, że będzie to duży krok naprzód.
Wyniki
Korzyści z biblioteki wzorców są chwalone w milionach artykułów na Medium. Dobrze wykonane ułatwiają tworzenie powiązanych produktów i zachowanie tożsamości. Oczywiście żadne z tych narzędzi nie stworzy magicznie systemu projektowania. Wymaga to starannego projektowania i projektowania CSS. Ale kiedy przychodzi czas na udostępnienie systemu projektowego całej firmie, Docz, Storybook i Styleguidist są świetnymi opcjami.
Od tłumacza. To moje pierwsze doświadczenie na Habré. Jeśli znajdziesz jakieś nieścisłości, lub masz sugestie dotyczące ulepszenia artykułu - napisz w wiadomości prywatnej.
Źródło: www.habr.com