Смернице за живот - МДКС и други оквири

Можда имате бољи пројекат отвореног кода, али ако нема добру документацију, велике су шансе да никада неће успети. У канцеларији, добра документација ће вас спречити да увек изнова одговарате на иста питања. Документација такође осигурава да људи могу схватити пројекат ако кључни запослени напусте компанију или се улоге промене. Смернице уживо помажу да се обезбеди интегритет података.

Ако треба да пишете дугачак текст, Маркдовн је одлична алтернатива ХТМЛ-у. Понекад Маркдовн синтакса није довољна. У овом случају, можемо користити ХТМЛ унутар њега. На пример, прилагођени елементи. Стога, ако градите систем дизајна са изворним веб компонентама, лако их је укључити у текстуалну документацију. Ако користите Реацт (или било који други ЈСКС оквир као што је Преацт или Вуе), исто можете учинити са МДКС-ом.

Овај чланак је широк преглед алата за писање документације и креирање смерница. Не користе сви овде наведени алати МДКС, али се он све више укључује у документационе алате.

Шта је МДКС?

фајл .mdx има исту синтаксу као Маркдовн, али вам омогућава да увезете интерактивне ЈСКС компоненте и уградите их у свој садржај. Подршка за Вуе компоненте је у алфа верзији. Да бисте почели да радите са МДКС-ом, само инсталирајте „Цреате Реацт Апп“. Постоје додаци за Нект.јс и Гатсби. Следећа верзија Доцусауруса (верзија 2) ће такође имати уграђену подршку.

Писање документације са Доцусаурусом

Докусаурус је написао на Фејсбуку. Користе га на сваком пројекту отвореног кода осим Реацт-а. Изван компаније га користе Редук, Преттиер, Гулп и Бабел.

Пројекти који користе Доцусаурус.

Доцусаурус се може користити за писање било који документацију, не само за описивање фронтенда. Има Реацт испод хаубе, али не морате бити упознати са њим да бисте га користили. Потребне су ваше Маркдовн датотеке, мало магије и добро структурирана, форматирана и читљива документација са прелепим дизајном је спремна.

Можете видети подразумевани шаблон Доцусаурус на веб локацији Редук.

Сајтови направљени помоћу Доцусаурус-а такође могу укључити блог заснован на Маркдовн-у. За истицање синтаксе, Присм.јс је одмах укључен. Упркос чињеници да се Доцусаурус појавио релативно недавно, на СтацкСхаре-у је препознат као најбољи алат 2018.

Друге опције за креирање садржаја

Доцусаурус је посебно дизајниран за креирање документације. Наравно, постоји милион и један начин да направите веб локацију – можете да примените сопствено решење на било ком језику, ЦМС-у или користите статички генератор сајтова.

На пример, документација за Реацт, ИБМ дизајн систем, Аполло и Гхост ЦМС користе Гатсби, статички генератор сајтова који се често користи за блогове. Ако радите са Вуе-ом, онда је ВуеПресс добра опција за вас. Друга опција је коришћење генератора написаног у Питхон-у – МкДоцс. Отворен је и конфигурисан са једном ИАМЛ датотеком. ГитБоок је такође добра опција, али је бесплатан само за отворене и некомерцијалне тимове. Такође можете једноставно да отпремите мардовн датотеке користећи гит и радите са њима у Гитхуб-у.

Документација компоненти: Доцз, Сторибоок и Стилегуидист

Смернице, дизајн система, библиотеке компоненти, како год да их назовете, постали су веома популарни у последње време. Појава компонентних оквира као што је Реацт и алати који се овде помињу омогућили су да се они трансформишу из сујетних пројеката у корисне алате.

Сторибоок, Доцз и Стилегуидист раде исту ствар: приказују интерактивне елементе и документују њихов АПИ. Пројекат може имати десетине или чак стотине компоненти, све са различитим стањима и стиловима. Ако желите да се компоненте поново користе, људи морају да знају да постоје. Да бисте то урадили, довољно је каталогизирати компоненте. Смернице пружају преглед свих ваших компоненти који је лак за претрагу. Ово помаже у одржавању визуелне доследности и избегавању понављања рада.

Ови алати пружају згодан начин за преглед различитих стања. Може бити тешко поновити свако стање компоненте у контексту стварне апликације. Уместо да кликнете на стварну апликацију, вреди развити засебну компоненту. Могуће је моделовати тешко доступна стања (на пример, стање учитавања).

Уз визуелну демонстрацију различитих стања и листу својстава, често је потребно написати општи опис садржаја – образложења дизајна, случајеве употребе или опис резултата тестирања корисника. Маркдовн је веома лако научити – у идеалном случају, смернице би требало да буду заједнички ресурс за дизајнере и програмере. Доцз, Стилегуидист и Сторибоок нуде начин за једноставно мешање Маркдовн-а са компонентама.

Доцз

Тренутно, Доцз ради само са Реацт-ом, али активно ради на подршци за Преацт, Вуе и веб компоненте. Доцз је најновији од три алата, али је успео да прикупи преко 14 звездица на Гитхубу. Доцз уводи две компоненте − <Playground> и < Props >. Они се увозе и користе у датотекама .mdx.

import { Playground, Props } from "docz";
import Button from "../src/Button";

## You can _write_ **markdown**
### You can import and use components

<Button>click</Button>

Можете умотати своје Реацт компоненте са <Playground>да направите аналогни уграђени ЦодеПен или ЦодеСандбок - то јест, видите своју компоненту и можете је уређивати.

<Playground>
  <Button>click</Button>
</Playground>

<Props> ће приказати сва доступна својства за дату Реацт компоненту, подразумеване вредности и да ли је особина потребна.

<Props of={Button} />

Лично, сматрам да је овај приступ заснован на МДКС-у најлакши за разумевање и најлакши за рад.

Ако сте љубитељ Гетсбијевог статичног генератора сајтова, Доцз нуди одличне интеграције.

водич за стил

Као иу Доцз-у, примери су написани коришћењем Маркдовн синтаксе. Стилегуидист користи блокове кода Маркдовн (троструки наводники) у регуларним датотекама .md датотеке, не у МДКС.

```js
<Button onClick={() => console.log('clicked')>Push Me</Button>

Блокови кода у Маркдовну обично само приказују код. Када користите Стилегуидист, било који блок кода са језичком ознаком js, jsx или javascript ће се приказати као Реацт компонента. Као и Доцз, код се може уређивати - можете променити својства и одмах видети резултат.

Стилегуидист ће аутоматски креирати листу својстава из декларација ПропТипес, Флов или Типесцрипт.

Стилегуидист сада подржава Реацт и Вуе.

Књига прича

Сторибоок се најављује као „окружење за развој компоненти корисничког интерфејса“. Уместо да пишете примере компоненти унутар Маркдовн или МДКС датотека, ви пишете приче унутар Јавасцрипт датотека. Прича документовати специфично стање компоненте. На пример, компонента може имати историју за стање учитавања и онемогућено стање (онеспособљен).

storiesOf('Button', module)
  .add('disabled', () => (
    <Button disabled>lorem ipsum</Button>
  ))

Књига прича је много сложенија од Стилегуидиста и Доцз-а. Али у исто време, ово је најпопуларнија опција, на Гитхубу пројекат има више од 36 звездица. Ово је пројекат отвореног кода са 000 сарадника и пратњом особља. Користе га Аирбнб, Алголиа, Атлассиан, Лифт и Салесфорце. Сторибоок подржава више оквира од конкуренције - Реацт, Реацт Нативе, Вуе, Ангулар, Митхрил, Ембер, Риот, Свелте и обичан ХТМЛ.

У наредном издању биће чипови из Доцз-а и МДКС се уводи.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

Нове функције Сторибоок-а ће се постепено уводити у наредних неколико месеци и изгледа да ће то бити велики корак напред.

Резултати

Предности библиотеке шаблона су похваљене у милионима чланака на Медиум-у. Када се добро ураде, олакшавају креирање сродних производа и одржавање идентитета. Наравно, ниједан од ових алата неће магично створити систем дизајна. Ово захтева пажљив дизајн и ЦСС дизајн. Али када дође време да се систем дизајна учини доступним целој компанији, Доцз, Сторибоок и Стилегуидист су одличне опције.

Од преводиоца. Ово је моје прво искуство на Хабреу. Ако нађете било какве нетачности, или имате предлоге за побољшање чланка - пишите у лично.

Извор: ввв.хабр.цом