Bạn có thể có dự án nguồn mở tốt nhất, nhưng nếu nó không có tài liệu tốt thì rất có thể nó sẽ không bao giờ thành công. Ở văn phòng, tài liệu tốt sẽ ngăn bạn trả lời những câu hỏi tương tự. Tài liệu cũng đảm bảo rằng mọi người có thể hiểu được dự án nếu nhân viên chủ chốt rời công ty hoặc vai trò thay đổi. Hướng dẫn sống động sẽ giúp đảm bảo tính toàn vẹn dữ liệu.
Nếu bạn cần viết văn bản dài, Markdown là một sự thay thế tuyệt vời cho HTML. Đôi khi cú pháp Markdown là không đủ. Trong trường hợp này chúng ta có thể sử dụng HTML bên trong nó. Ví dụ: các yếu tố tùy chỉnh. Do đó, nếu bạn đang xây dựng một hệ thống thiết kế với các thành phần web gốc, chúng có thể dễ dàng được đưa vào tài liệu văn bản. Nếu bạn đang sử dụng React (hoặc bất kỳ khung JSX nào khác như Preact hoặc Vue), bạn có thể làm điều tương tự với MDX.
Bài viết này là tổng quan bao quát về các công cụ viết tài liệu và tạo hướng dẫn. Không phải tất cả các công cụ được liệt kê ở đây đều sử dụng MDX, nhưng nó ngày càng được đưa vào các công cụ tài liệu.
MDX là gì?
hồ sơ .mdx có cú pháp tương tự như Markdown, nhưng cho phép bạn nhập các thành phần JSX tương tác và nhúng chúng vào nội dung của bạn. Hỗ trợ cho các thành phần Vue ở dạng alpha. Để bắt đầu làm việc với MDX, chỉ cần cài đặt “Tạo ứng dụng React”. Có plugin cho Next.js và Gatsby. Phiên bản tiếp theo của Docusaurus (phiên bản 2) cũng sẽ có hỗ trợ riêng.
Viết tài liệu với Docusaurus
Docusaurus đã viết trên Facebook. Họ sử dụng nó trên mọi dự án nguồn mở ngoại trừ React. Bên ngoài công ty, nó được sử dụng bởi Redux, Prettier, Gulp và Babel.
Các dự án sử dụng Docusaurus.
Docusaurus có thể được sử dụng để viết bất kỳ tài liệu, không chỉ để mô tả giao diện người dùng. Nó có React, nhưng bạn không cần phải làm quen với nó để sử dụng nó. Nó cần các tệp Markdown của bạn, một chút ma thuật và tài liệu có cấu trúc tốt, được định dạng và dễ đọc với thiết kế đẹp mắt đã sẵn sàng.
Trên trang web Redux bạn có thể thấy mẫu Docusaurus tiêu chuẩn
Các trang web được xây dựng bằng Docusaurus cũng có thể bao gồm blog dựa trên Markdown. Prism.js được kết nối ngay lập tức để làm nổi bật cú pháp. Mặc dù Docusaurus xuất hiện tương đối gần đây nhưng nó đã được công nhận là công cụ tốt nhất năm 2018 trên StackShare.
Tùy chọn tạo nội dung khác
Docusaurus được thiết kế đặc biệt để tạo tài liệu. Tất nhiên, có một triệu lẻ một cách để tạo một trang web - bạn có thể triển khai giải pháp của riêng mình bằng bất kỳ ngôn ngữ, CMS nào hoặc sử dụng trình tạo trang tĩnh.
Ví dụ: tài liệu về React, hệ thống thiết kế IBM, Apollo và Ghost CMS sử dụng Gatsby - một trình tạo trang tĩnh thường được sử dụng cho blog. Nếu bạn làm việc với Vue thì VuePress là một lựa chọn tốt cho bạn. Một tùy chọn khác là sử dụng trình tạo được viết bằng Python - MkDocs. Nó là nguồn mở và được định cấu hình bằng một tệp YAML duy nhất. GitBook cũng là một lựa chọn tốt nhưng chỉ miễn phí cho các nhóm công cộng và phi thương mại. Bạn cũng có thể chỉ cần tải lên các tệp mardown bằng Git và làm việc với chúng trong Github.
Các thành phần tài liệu: Docz, Storybook và Styleguidist
Nguyên tắc, thiết kế hệ thống, thư viện thành phần - bạn gọi chúng là gì cũng được, gần đây nó đã trở nên rất phổ biến. Sự ra đời của các framework thành phần như React và các công cụ được đề cập ở đây đã biến chúng từ những dự án phù phiếm thành những công cụ hữu ích.
Storybook, Docz và Styleguidist đều làm điều tương tự: hiển thị các phần tử tương tác và ghi lại API của chúng. Một dự án có thể có hàng chục hoặc thậm chí hàng trăm thành phần - tất cả đều có trạng thái và phong cách khác nhau. Nếu bạn muốn các thành phần được tái sử dụng, mọi người cần biết chúng tồn tại. Để làm điều này, chỉ cần lập danh mục các thành phần. Nguyên tắc cung cấp cái nhìn tổng quan dễ tìm về tất cả các thành phần của bạn. Điều này giúp duy trì tính nhất quán về mặt hình ảnh và tránh công việc lặp đi lặp lại.
Những công cụ này cung cấp một cách thuận tiện để xem các trạng thái khác nhau. Có thể khó tái tạo từng trạng thái của một thành phần trong bối cảnh của một ứng dụng thực tế. Thay vì nhấp vào ứng dụng thực tế, bạn nên phát triển một thành phần riêng biệt. Các trạng thái khó tiếp cận (chẳng hạn như trạng thái tải) có thể được mô phỏng.
Cùng với sự trình diễn trực quan về các trạng thái khác nhau và danh sách các thuộc tính, thường cần phải viết mô tả chung về nội dung - lý do thiết kế, trường hợp sử dụng hoặc mô tả kết quả thử nghiệm của người dùng. Markdown rất dễ học - lý tưởng nhất là các hướng dẫn phải là tài nguyên chung cho các nhà thiết kế và nhà phát triển. Docz, Styleguidist và Storybook cung cấp cách dễ dàng kết hợp Markdown với các thành phần.
bác sĩ
Hiện tại Docz chỉ hoạt động với React, nhưng công việc tích cực đang được tiến hành để hỗ trợ các thành phần Preact, Vue và web. Docz là công cụ mới nhất trong số ba công cụ này nhưng nó đã thu thập được hơn 14 sao trên Github. Docz giới thiệu hai thành phần − <Playground> и < Props >. Chúng được nhập và sử dụng trong các tập tin .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Bạn có thể gói các thành phần React của riêng mình bằng <Playground>để tạo một bản tương tự của CodePen hoặc CodeSandbox tích hợp sẵn - nghĩa là bạn nhìn thấy thành phần của mình và có thể chỉnh sửa nó.
<Playground>
<Button>click</Button>
</Playground><Props> sẽ hiển thị tất cả các thuộc tính có sẵn cho một thành phần React nhất định, các giá trị mặc định và liệu thuộc tính đó có bắt buộc hay không.
<Props of={Button} />Cá nhân tôi thấy cách tiếp cận dựa trên MDX này là dễ hiểu nhất và dễ làm việc nhất.
Nếu bạn là người hâm mộ trình tạo trang tĩnh Gatsby, Docz cung cấp một sự tích hợp tuyệt vời.
Hướng dẫn mẫu
Giống như Docz, các ví dụ được viết bằng cú pháp Markdown. Styleguidist sử dụng khối mã Markdown (dấu ngoặc kép) trong các tệp thông thường .md tập tin, không phải MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Các khối mã trong Markdown thường chỉ hiển thị mã. Khi sử dụng Styleguidist, bất kỳ khối mã nào có thẻ ngôn ngữ js, jsx hoặc javascript sẽ hiển thị dưới dạng thành phần React. Giống như Docz, mã có thể chỉnh sửa được - bạn có thể thay đổi các thuộc tính và xem ngay kết quả.
Styleguidist sẽ tự động tạo bảng thuộc tính từ các khai báo PropTypes, Flow hoặc Typescript.
Styleguidist hiện hỗ trợ React và Vue.
Quyển truyện
Storybook tự định vị mình là “môi trường phát triển thành phần giao diện người dùng”. Thay vì viết các thành phần mẫu bên trong tệp Markdown hoặc MDX, bạn viết những câu chuyện bên trong các tập tin Javascript. Câu chuyện ghi lại trạng thái cụ thể của một thành phần. Ví dụ: một thành phần có thể có lịch sử về trạng thái được tải và trạng thái bị vô hiệu hóa (bị vô hiệu hóa).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook phức tạp hơn nhiều so với Styleguidist và Docz. Nhưng đồng thời, đây là lựa chọn phổ biến nhất; dự án có hơn 36 sao trên Github. Đây là một dự án nguồn mở với 000 người đóng góp và nhân viên toàn thời gian. Nó được sử dụng bởi Airbnb, Algolia, Atlassian, Lyft và Salesforce. Storybook hỗ trợ nhiều framework hơn các đối thủ cạnh tranh - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte và HTML thông thường.
Trong phiên bản tương lai sẽ có các tính năng từ Docz và MDX sẽ được giới thiệu.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Các tính năng mới của Storybook sẽ dần được triển khai trong vài tháng tới và có vẻ như đây sẽ là một bước tiến lớn.
Kết quả
Lợi ích của thư viện mẫu được ca ngợi trong hàng triệu bài báo trên Medium. Khi thực hiện tốt, chúng sẽ giúp việc tạo ra các sản phẩm liên quan và duy trì bản sắc trở nên dễ dàng hơn. Tất nhiên, không có công cụ nào trong số này có thể tạo ra một hệ thống thiết kế một cách kỳ diệu. Điều này đòi hỏi thiết kế và CSS cẩn thận. Nhưng khi cần làm cho toàn bộ công ty có thể tiếp cận được một hệ thống thiết kế thì Docz, Storybook và Styleguidist là những lựa chọn tuyệt vời.
Từ người dịch. Đây là trải nghiệm đầu tiên của tôi về Habré. Nếu bạn tìm thấy bất kỳ điểm nào không chính xác hoặc có đề xuất cải thiện bài viết, hãy viết thư cho tôi bằng tin nhắn cá nhân.
Nguồn: www.habr.com