En iyi açık kaynak projeye sahip olabilirsiniz, ancak iyi bir belgelendirmeye sahip değilse büyük olasılıkla hiçbir zaman başarılı olamayacaktır. Ofiste iyi bir dokümantasyon aynı soruları yanıtlamanızı engelleyecektir. Dokümantasyon aynı zamanda kilit çalışanların şirketten ayrılması veya rollerin değişmesi durumunda insanların projeyi anlayabilmesini de sağlar. Yaşam kuralları veri bütünlüğünün sağlanmasına yardımcı olacaktır.
Uzun metin yazmanız gerekiyorsa Markdown, HTML'ye harika bir alternatiftir. Bazen Markdown sözdizimi yeterli değildir. Bu durumda içinde HTML kullanabiliriz. Örneğin, özel öğeler. Bu nedenle, yerel web bileşenleriyle bir tasarım sistemi oluşturuyorsanız bunlar kolayca metin belgelerine dahil edilebilir. React (veya Preact veya Vue gibi başka bir JSX çerçevesi) kullanıyorsanız, aynı şeyi MDX ile de yapabilirsiniz.
Bu makale, belge yazmaya ve kılavuz oluşturmaya yönelik araçlara geniş bir genel bakış sunmaktadır. Burada listelenen araçların tümü MDX kullanmamaktadır ancak belgeleme araçlarına giderek daha fazla dahil edilmektedir.
MDX nedir?
Dosya .mdx Markdown ile aynı sözdizimine sahiptir ancak etkileşimli JSX bileşenlerini içe aktarmanıza ve bunları içeriğinize yerleştirmenize olanak tanır. Vue bileşenleri desteği alfa aşamasındadır. MDX ile çalışmaya başlamak için “Create React App” uygulamasını kurmanız yeterli. Next.js ve Gatsby için eklentiler var. Docusaurus'un bir sonraki sürümü (sürüm 2) de yerel desteğe sahip olacak.
Docusaurus ile dokümantasyon yazma
Docusaurus Facebook'ta yazdı. React dışında her açık kaynaklı projede kullanıyorlar. Şirket dışında Redux, Prettier, Gulp ve Babel tarafından da kullanılmaktadır.
Docusaurus kullanan projeler.
Docusaurus yazmak için kullanılabilir herhangi belgeler, yalnızca ön ucu tanımlamak için değil. Temelinde React var ama kullanmak için ona aşina olmanıza gerek yok. Markdown dosyalarınızı alır, bir tutam sihirli ve iyi yapılandırılmış, biçimlendirilmiş ve okunabilir güzel bir tasarıma sahip belgeler hazırdır.
Redux web sitesinde standart Docusaurus şablonunu görebilirsiniz.
Docusaurus ile oluşturulan web siteleri aynı zamanda Markdown tabanlı bir blog da içerebilir. Prism.js, sözdizimi vurgulaması için hemen bağlanır. Docusaurus nispeten yakın zamanda ortaya çıkmasına rağmen StackShare'de 2018'in en iyi aracı olarak kabul edildi.
Diğer İçerik Oluşturma Seçenekleri
Docusaurus özellikle dokümantasyon oluşturmak için tasarlanmıştır. Elbette, bir web sitesi oluşturmanın milyonlarca bir yolu vardır; kendi çözümünüzü herhangi bir dilde, CMS'de dağıtabilir veya statik bir site oluşturucu kullanabilirsiniz.
Örneğin, React, IBM tasarım sistemi, Apollo ve Ghost CMS belgeleri, genellikle bloglar için kullanılan statik bir site oluşturucu olan Gatsby'yi kullanır. Vue ile çalışıyorsanız VuePress sizin için iyi bir seçenektir. Diğer bir seçenek ise Python - MkDocs ile yazılmış bir oluşturucu kullanmaktır. Açık kaynaktır ve tek bir YAML dosyası kullanılarak yapılandırılmıştır. GitBook da iyi bir seçenektir ancak yalnızca halka açık ve ticari olmayan ekipler için ücretsizdir. Ayrıca Git'i kullanarak mardown dosyalarını kolayca yükleyebilir ve Github'da onlarla çalışabilirsiniz.
Belgeleme bileşenleri: Docz, Storybook ve Styleguidist
Yönergeler, sistem tasarımı, bileşen kitaplıkları; bunlara ne ad verirseniz verin, son zamanlarda çok popüler hale geldi. React gibi bileşen çerçevelerinin ve burada bahsedilen araçların ortaya çıkışı, onları gösterişli projelerden kullanışlı araçlara dönüştürdü.
Storybook, Docz ve Styleguidist'in hepsi aynı şeyi yapar: etkileşimli öğeleri görüntüler ve API'lerini belgelendirir. Bir proje, hepsi farklı durum ve stillere sahip düzinelerce, hatta yüzlerce bileşene sahip olabilir. Bileşenlerin yeniden kullanılmasını istiyorsanız insanların bunların var olduğunu bilmesi gerekir. Bunu yapmak için bileşenleri kataloglamanız yeterlidir. Yönergeler, tüm bileşenleriniz hakkında bulunması kolay bir genel bakış sağlar. Bu, görsel tutarlılığın korunmasına ve tekrarlanan işlerin önlenmesine yardımcı olur.
Bu araçlar farklı durumları görüntülemek için uygun bir yol sağlar. Bir bileşenin her durumunu gerçek bir uygulama bağlamında yeniden oluşturmak zor olabilir. Gerçek uygulamaya tıklamak yerine ayrı bir bileşen geliştirmeye değer. Ulaşılması zor durumlar (yükleme durumları gibi) simüle edilebilir.
Çeşitli durumların görsel bir gösteriminin ve bir özellik listesinin yanı sıra, genellikle içeriğin genel bir tanımını (tasarım gerekçeleri, kullanım senaryoları veya kullanıcı testi sonuçlarının açıklamaları) yazmak gerekir. Markdown'ın öğrenilmesi çok kolaydır; ideal olarak kılavuzlar tasarımcılar ve geliştiriciler için ortak bir kaynak olmalıdır. Docz, Styleguidist ve Storybook, Markdown'ı bileşenlerle kolayca karıştırmanın bir yolunu sunar.
belge
Şu anda Docz yalnızca React ile çalışmaktadır ancak Preact, Vue ve web bileşenlerini desteklemek için aktif çalışmalar devam etmektedir. Docz, üç araçtan en yenisidir ancak Github'da 14'den fazla yıldız toplamayı başarmıştır. Docz iki bileşeni tanıtıyor: <Playground> и < Props >. İçe aktarılır ve dosyalarda kullanılırlar .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Kendi React bileşenlerinizi şununla sarabilirsiniz: <Playground>yerleşik CodePen veya CodeSandbox'ın bir analogunu oluşturmak için; yani bileşeninizi görürsünüz ve onu düzenleyebilirsiniz.
<Playground>
<Button>click</Button>
</Playground><Props> belirli bir React bileşeni için mevcut tüm özellikleri, varsayılan değerleri ve özelliğin gerekli olup olmadığını gösterecektir.
<Props of={Button} />Şahsen ben bu MDX tabanlı yaklaşımın anlaşılması en kolay ve üzerinde çalışılması en kolay yaklaşım olduğunu düşünüyorum.
Gatsby statik site oluşturucusunun hayranıysanız Docz harika bir entegrasyon sunar.
Stil rehberi
Docz gibi örnekler de Markdown sözdizimi kullanılarak yazılmıştır. Styleguidist normal dosyalarda Markdown kod bloklarını (üçlü tırnak) kullanır .md dosyalar, MDX değil.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Markdown'daki kod blokları genellikle yalnızca kodu gösterir. Styleguidist'i kullanırken, dil etiketine sahip herhangi bir kod bloğu js, jsx veya javascript bir React bileşeni olarak işlenecektir. Docz gibi kod da düzenlenebilir; özellikleri değiştirebilir ve sonucu anında görebilirsiniz.
Styleguidist, PropTypes, Flow veya Typescript bildirimlerinden otomatik olarak bir özellik tablosu oluşturacaktır.
Styleguidist şu anda React ve Vue'yu desteklemektedir.
Hikaye kitabı
Storybook kendisini bir "Kullanıcı arayüzü bileşeni geliştirme ortamı" olarak konumlandırıyor. Markdown veya MDX dosyalarının içine örnek bileşenler yazmak yerine şunu yazarsınız: hikayeler Javascript dosyalarının içinde. Öykü Bir bileşenin spesifik durumunu belgeleyin. Örneğin, bir bileşenin yüklü bir durum ve devre dışı bırakılmış bir durum için geçmişleri olabilir (özürlü).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook, Styleguidist ve Docz'dan çok daha karmaşıktır. Ancak aynı zamanda bu en popüler seçenek; projenin Github'da 36'den fazla yıldızı var. 000 katılımcısı ve tam zamanlı personeli olan açık kaynaklı bir projedir. Airbnb, Algolia, Atlassian, Lyft ve Salesforce tarafından kullanılmaktadır. Storybook rakiplerinden daha fazla çerçeveyi destekler - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte ve normal HTML.
Gelecekteki bir sürümde Docz'un özellikleri olacak ve MDX tanıtılacak.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Storybook'un yeni özellikleri önümüzdeki birkaç ay içinde kademeli olarak kullanıma sunulacak ve ileriye doğru büyük bir adım olacak gibi görünüyor.
sonuçlar
Bir desen kütüphanesinin faydaları Medium'daki milyonlarca makalede övülmektedir. İyi uygulandığında ilgili ürünleri yaratmayı ve kimliği korumayı kolaylaştırırlar. Elbette bu araçların hiçbiri sihirli bir şekilde bir tasarım sistemi yaratmayacak. Bu, dikkatli tasarım ve CSS gerektirir. Ancak iş bir tasarım sistemini tüm şirketin erişimine açmanın zamanı geldiğinde Docz, Storybook ve Styleguidist harika seçeneklerdir.
Çevirmenden. Bu benim Habré'deki ilk deneyimim. Herhangi bir yanlışlık bulursanız veya makaleyi geliştirmek için önerileriniz varsa, bana kişisel bir mesajla yazın.
Kaynak: habr.com