You may have a better open source project, but if it doesn't have good documentation, chances are it will never take off. In the office, good documentation will keep you from answering the same questions over and over. Documentation also ensures that people can make sense of the project if key employees leave the company or roles change. Live guidelines help ensure data integrity.
If you need to write long text, Markdown is a great alternative to HTML. Sometimes the Markdown syntax isn't enough. In this case, we can use HTML inside it. For example, custom elements. Therefore, if you are building a design system with native web components, it is easy to include them in text documentation. If you're using React (or any other JSX framework like Preact or Vue), you can do the same with MDX.
This article is a broad overview of tools for writing documentation and creating a guideline. Not all of the tools listed here use MDX, but it is increasingly being included in documentation tools.
What is MDX?
File .mdx has the same syntax as Markdown but allows you to import interactive JSX components and embed them in your content. Support for Vue components is in alpha. In order to start working with MDX, just install "Create React App". There are plugins for Next.js and Gatsby. The next version of Docusaurus (version 2) will also have built-in support.
Writing documentation with Docusaurus
Docusaurus wrote on Facebook. They use it on every open source project except React. Outside the company, Redux, Prettier, Gulp, and Babel use it.
Projects that use Docusaurus.
Docusaurus can be used to write any documentation, not just for describing the frontend. It has React under the hood, but you don't have to be familiar with it to use it. It takes your Markdown files, a pinch of magic and well-structured, formatted and readable documentation with a beautiful design is ready.
You can see the default Docusaurus template on the Redux website.
Sites built with Docusaurus can also include a Markdown-based blog. For syntax highlighting, Prism.js is immediately included. Despite the fact that Docusaurus has appeared relatively recently, it was recognized as the best tool of 2018 on StackShare.
Other Content Creation Options
Docusaurus is specifically designed for creating documentation. Of course, there are a million and one ways to make a website - you can deploy your own solution in any language, CMS, or use a static site generator.
For example, the documentation for React, the IBM design system, Apollo, and Ghost CMS use Gatsby, a static site generator often used for blogs. If you are working with Vue then VuePress is a good option for you. Another option is to use a generator written in Python - MkDocs. It is open and configured with a single YAML file. GitBook is also a good option, but it's only free for open and non-commercial teams. You can also just upload mardown files using git and work with them in Github.
Component Documentation: Docz, Storybook and Styleguidist
Guidelines, system design, component libraries, whatever you want to call them, these have become very popular lately. The emergence of component frameworks such as React and the tools mentioned here has made it possible to transform them from vanity projects into useful tools.
Storybook, Docz and Styleguidist do the same thing: display interactive elements and document their API. A project can have dozens or even hundreds of components, all with different states and styles. If you want components to be reused, people need to know that they exist. To do this, it is enough to catalog the components. Guidelines provide an easy-to-search overview of all your components. This helps maintain visual consistency and avoid repetitive work.
These tools provide a convenient way to view various states. It can be difficult to replicate every state of a component in the context of a real application. Instead of clicking on the actual application, it's worth developing a separate component. It is possible to model hard-to-reach states (for example, loading state).
Along with a visual demonstration of various states and a list of properties, it is often necessary to write a general description of the content - design rationales, use cases, or a description of the results of user testing. Markdown is very easy to learn - ideally, guidelines should be a shared resource for designers and developers. Docz, Styleguidist, and Storybook offer a way to easily mix Markdown with components.
Docz
Currently, Docz only works with React, but is actively working on support for Preact, Vue, and web components. Docz is the most recent of the three tools, but has been able to collect over 14 stars on Github. Docz introduces two components β <Playground> ΠΈ < Props >. They are imported and used in files .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>You can wrap your own React components with <Playground>to create an analogue of the built-in CodePen or CodeSandbox - that is, you see your component and can edit it.
<Playground>
<Button>click</Button>
</Playground><Props> will show all available properties for the given React component, default values ββand whether the property is required.
<Props of={Button} />Personally, I find this MDX-based approach the easiest to understand and the easiest to work with.
If you're a fan of Gatsby's static site generator, Docz offers great integrations.
style guidist
As in Docz, examples are written using Markdown syntax. Styleguidist uses Markdown code blocks (triple quotes) in regular files .md files, not in MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Code blocks in Markdown usually just show the code. When using Styleguidist, any block of code with a language tag js, jsx or javascript will render as a React component. Like Docz, the code is editable - you can change properties and instantly see the result.
Styleguidist will automatically create a property sheet from PropTypes, Flow or Typescript declarations.
Styleguidist now supports React and Vue.
story book
Storybook bills itself as a "UI component development environment". Instead of writing component examples inside Markdown or MDX files, you write stories inside Javascript files. History document the specific state of a component. For example, a component might have histories for a loading state and a disabled state (disabled).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook is much more complex than Styleguidist and Docz. But at the same time, this is the most popular option, on Github the project has more than 36 stars. This is an open source project with 000 contributors and staff accompaniment. It is used by Airbnb, Algolia, Atlassian, Lyft and Salesforce. Storybook supports more frameworks than the competition - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, and plain HTML.
In a future release, there will be chips from Docz and MDX is being introduced.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>The new Storybook features will roll out gradually over the next few months, and it looks like it will be a big step forward.
Results
The benefits of the pattern library are lauded in millions of articles on Medium. When done well, they make it easier to create related products and maintain an identity. Of course, none of these tools will magically create a design system. This requires careful design and CSS design. But when it comes time to make the design system available to the whole company, Docz, Storybook and Styleguidist are great options.
From a translator. This is my first experience on HabrΓ©. If you find any inaccuracies, or have suggestions for improving the article - write in a personal.
Source: habr.com