The Legendary Fountain of Truth: Componentize Your Documentation!

Rate this content
Bookmark

"In Space, No One Can Hear You Scream." The same goes for your super-brand-new-revolutionary project: Documentation is the key to get people speaking about it.

Building well-fitted documentation can be tricky. Having it updated each time you release a new feature had to be a challenging part of your adventure. We tried many things to prevent the gap between doc and code: code-generated documentation, live examples a-la-Storybook, REPL...

It's time for a new era of documentation where people-oriented content lives along with code examples: this talk will guide you from Documentation Best Practices – covered from years of FOSS collaborative documentation – to the new fancy world of Components in Markdown: MDX, MDJS, MD Vite, and all.

Let's build shiny documentation for brilliant people!

This talk has been presented at React Advanced Conference 2021, check out the latest edition of this React Conference.

FAQ

Documentation is crucial in a command-driven era because it ensures that users understand how to use your project, whether it's a library, component, design system, or application interface. Proper documentation keeps your project in sync with its codebase and helps sustain its usability over time.

Living documentation is challenging because duplicating code from your codebase to your documentation can lead to desynchronization. Keeping documentation in sync with the codebase is essential to maintain its relevance and usability.

The Diataxis framework is a documentation framework used by many companies. It organizes documentation into four parts: READMEs, O2s (guides and recipes), FAQs, and main pages (advanced technical content). This structured approach helps in managing different elements of documentation effectively.

In component-driven development, the Diataxis framework can be applied by embedding components in documentation. This approach allows for live testing, sandboxing, and comprehensive documentation of components, making it easier to understand and use each part of the project.

MDX is an extension of Markdown that allows embedding JSX (JavaScript XML) in Markdown documents. This enables the inclusion of interactive components, live code examples, and more advanced features within documentation, making it more dynamic and useful.

Keeping documentation and code together ensures that both are always in sync. This reduces the risk of outdated or incorrect documentation and makes it easier to maintain and update both code and documentation simultaneously.

Tools that support MDX for documentation include Storybook, Docusaurus, and documentation-oriented solutions like DivRiot's Backlight. These tools provide layouts, playgrounds, props tables, and other features to enhance documentation.

Embedding components in documentation allows developers to test, experiment, and document components in an isolated environment. This leads to better maintenance, easier testing, and more comprehensive and interactive documentation.

Playgrounds are sandbox environments where components can be rendered and interacted with within the documentation. Props tables automatically generate tables of component properties, helping users understand how to customize and use the components.

To migrate existing Markdown documentation to MDX, organize the documentation according to the Diataxis framework, select the appropriate tools (either naked tools or documentation frameworks), and start embedding components within the documentation using MDX syntax.

m4dz
m4dz
24 min
25 Oct, 2021

Comments

Sign in or register to post your comment.

Video Summary and Transcription

Welcome to this session about documentation in a command-driven era. The Data Axis framework provides a comprehensive approach to documentation, covering different areas of the development process. Component-driven development and MDX syntax enable faster development, simpler maintenance, and better reusability. Embedding components in Markdown using MDX allows for more advanced and useful documentation creation. Tools like Storybook and Duxy with MDX support are recommended for documentation solutions. Embedding documentation directly within components and migrating to MDX offer a comprehensive documentation experience and open up new possibilities for embedding and improving documentation.

1. Documentation in a Command-Driven Era

Short description:

Welcome to this session about documentation in a command-driven era. Your documentation is the key to the success of your project. Keep your documentation associated with your code to avoid desynchronization. We need a single source of truth, which is your codebase. Keep the documentation in sync with the codebase and embed your codebase in your documentation.

Hi everyone! Nice to have you here! Welcome to this session about documentation in a command-driven era. So we're gonna talk about documentation as a key success of your project. I mean, nevertheless, you are working on a library, a single component, a whole design system or a final interface of an application, your documentation is the key to the success of your project.

Because without a proper documentation, no one gonna have a single clue about how is it working and how you are supposed to use your project or use any part of your project. So you have to keep your documentation properly associated with your code. Fact is living documentation is a pain today just because if you have to duplicate your code from your codebase to your documentation, you obviously leads to a desynchronization at some point of your documentation versus your codebase. So you have to keep them in sync if you want to be ready to just simply use and sustain your documentation in time so to have your project ready to be used by anyone in the past and in the future.

So we tried many things to to keep things organized between your documentation and your codebase. We tried things like storybook, we tried things like ambed, erpl in your documentation by itself, we tried many things but the real truth is that we need a single source of truth and this single source is your codebase by itself. Not your documentation, not your examples that will be outdated at some point. You need something that is definitely the single point where everything leave and this is directly in your codebase. So we do have to do something to keep the documentation in sync with the codebase and we do need something to embed your codebase in your documentation level.

2. The Data Axis Framework

Short description:

This is a documentation framework that many companies are using right now. It is oriented in four parts: READMES, O2s, FAQs, and main pages. READMES serve as the entry point for users, providing getting started guides. O2s are guides or recipes for working with specific parts of the project. FAQs contain discussions and histories, helping to understand project choices and interactions. Main pages provide advanced technical content. These four parts cover different areas of the development process.

So just a reminder about the data axis framework. This is a documentation framework that many companies are using right now. This documentation framework is oriented in four parts. All these four parts are the dedicated parts to your documentation and all you have to do is split different elements of your documentation in the same area.

So first entry is the READMES. READMES are the entry point of your documentation. When a user is coming to your new documentation and don't have any clue where to start, the READMES are the correct entry point. There are something like getting started guides, this kind of stuff. Something where you can re-play all the time the same path and the same steps in your development process and you will have the same result at your hand. This is the really good way to just put your hands in your project.

The second part is the O2s. The O2s are more guides or recipes and they are dedicated at how you want to work with this part of the project or how can I embed my project in a React app, how can I use my library with this kind of back-end and so on. The guides presume that you have a preset and in this particular preset there are guides, there are different recipes on how you could use your project in different aspects of the development.

Third part are the FAQs. In them you have all the discussions, all the histories, why is this project of this choice, this particular use of this tool, or this preset and so on. This is where all the history of the project is living and it helps to understand why did we choose this particular setup at some point and it helps to understand how everything interacts together.

Then the final parts are main pages in the Unix era or more specifically advanced documentation about a dedicated part, how this component is working, how this library is using at some point in the project. This is a comprehensive guide of particular deep technical content. These four parts are attached to four different areas. Readmes and O2s are the practices points. Each time you are asking, OK, I'm working on a new part of the documentation, and I want to add some new content in it, which topic it is related on? If it's related to practices, then this is the right point to have a look at. So, is it something like an entry point, like a getting started stuff, or is it a guide dedicated to more different access in the specific area of specific parts of the development process? So, Readmes and Hotos, this is practice, where the packs and the main pages are more dedicated to understanding the project and the basis of the project. But the Readmes and the FAQs are also the learning parts, where you are learning how it is working and why it is working this way. Where the Hotos are more dedicated to... And the main pages are more dedicated to where... When I want to use the project, which part do I have to keep an eye on? Is it on the Hotos? Is it on the main pages? I am looking for a deep-dive technical content, or I'm looking to a dedicated guide on this particular topic, because this is what I am looking for at this point. So, when you have this framework in mind, you are working on a well-fitted documentation for any kind of project. So, I do recommend you to keep an eye on the Attacksys framework, if you don't know it right now, and to try to stack your documentation to it, because this is something really, really useful in your everyday work. But, we are now working in a document... In a component-driven development area.

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

Don't Solve Problems, Eliminate Them
React Advanced Conference 2021React Advanced Conference 2021
39 min
Don't Solve Problems, Eliminate Them
Top Content
Kent C. Dodds discusses the concept of problem elimination rather than just problem-solving. He introduces the idea of a problem tree and the importance of avoiding creating solutions prematurely. Kent uses examples like Tesla's electric engine and Remix framework to illustrate the benefits of problem elimination. He emphasizes the value of trade-offs and taking the easier path, as well as the need to constantly re-evaluate and change approaches to eliminate problems.
Using useEffect Effectively
React Advanced Conference 2022React Advanced Conference 2022
30 min
Using useEffect Effectively
Top Content
Today's Talk explores the use of the useEffect hook in React development, covering topics such as fetching data, handling race conditions and cleanup, and optimizing performance. It also discusses the correct use of useEffect in React 18, the distinction between Activity Effects and Action Effects, and the potential misuse of useEffect. The Talk highlights the benefits of using useQuery or SWR for data fetching, the problems with using useEffect for initializing global singletons, and the use of state machines for handling effects. The speaker also recommends exploring the beta React docs and using tools like the stately.ai editor for visualizing state machines.
Full Stack Documentation
JSNation 2022JSNation 2022
28 min
Full Stack Documentation
Top Content
The Talk discusses the shift to full-stack frameworks and the challenges of full-stack documentation. It highlights the power of interactive tutorials and the importance of user testing in software development. The Talk also introduces learn.svelte.dev, a platform for learning full-stack tools, and discusses the roadmap for SvelteKit and its documentation.
Design Systems: Walking the Line Between Flexibility and Consistency
React Advanced Conference 2021React Advanced Conference 2021
47 min
Design Systems: Walking the Line Between Flexibility and Consistency
Top Content
The Talk discusses the balance between flexibility and consistency in design systems. It explores the API design of the ActionList component and the customization options it offers. The use of component-based APIs and composability is emphasized for flexibility and customization. The Talk also touches on the ActionMenu component and the concept of building for people. The Q&A session covers topics such as component inclusion in design systems, API complexity, and the decision between creating a custom design system or using a component library.
React Concurrency, Explained
React Summit 2023React Summit 2023
23 min
React Concurrency, Explained
Top Content
Watch video: React Concurrency, Explained
React 18's concurrent rendering, specifically the useTransition hook, optimizes app performance by allowing non-urgent updates to be processed without freezing the UI. However, there are drawbacks such as longer processing time for non-urgent updates and increased CPU usage. The useTransition hook works similarly to throttling or bouncing, making it useful for addressing performance issues caused by multiple small components. Libraries like React Query may require the use of alternative APIs to handle urgent and non-urgent updates effectively.
Managing React State: 10 Years of Lessons Learned
React Day Berlin 2023React Day Berlin 2023
16 min
Managing React State: 10 Years of Lessons Learned
Top Content
Watch video: Managing React State: 10 Years of Lessons Learned
This Talk focuses on effective React state management and lessons learned over the past 10 years. Key points include separating related state, utilizing UseReducer for protecting state and updating multiple pieces of state simultaneously, avoiding unnecessary state syncing with useEffect, using abstractions like React Query or SWR for fetching data, simplifying state management with custom hooks, and leveraging refs and third-party libraries for managing state. Additional resources and services are also provided for further learning and support.

Workshops on related topic

React Performance Debugging Masterclass
React Summit 2023React Summit 2023
170 min
React Performance Debugging Masterclass
Top Content
Featured WorkshopFree
Ivan Akulov
Ivan Akulov
Ivan’s first attempts at performance debugging were chaotic. He would see a slow interaction, try a random optimization, see that it didn't help, and keep trying other optimizations until he found the right one (or gave up).
Back then, Ivan didn’t know how to use performance devtools well. He would do a recording in Chrome DevTools or React Profiler, poke around it, try clicking random things, and then close it in frustration a few minutes later. Now, Ivan knows exactly where and what to look for. And in this workshop, Ivan will teach you that too.
Here’s how this is going to work. We’ll take a slow app → debug it (using tools like Chrome DevTools, React Profiler, and why-did-you-render) → pinpoint the bottleneck → and then repeat, several times more. We won’t talk about the solutions (in 90% of the cases, it’s just the ol’ regular useMemo() or memo()). But we’ll talk about everything that comes before – and learn how to analyze any React performance problem, step by step.
(Note: This workshop is best suited for engineers who are already familiar with how useMemo() and memo() work – but want to get better at using the performance tools around React. Also, we’ll be covering interaction performance, not load speed, so you won’t hear a word about Lighthouse 🤐)
React Hooks Tips Only the Pros Know
React Summit Remote Edition 2021React Summit Remote Edition 2021
177 min
React Hooks Tips Only the Pros Know
Top Content
Featured Workshop
Maurice de Beijer
Maurice de Beijer
The addition of the hooks API to React was quite a major change. Before hooks most components had to be class based. Now, with hooks, these are often much simpler functional components. Hooks can be really simple to use. Almost deceptively simple. Because there are still plenty of ways you can mess up with hooks. And it often turns out there are many ways where you can improve your components a better understanding of how each React hook can be used.You will learn all about the pros and cons of the various hooks. You will learn when to use useState() versus useReducer(). We will look at using useContext() efficiently. You will see when to use useLayoutEffect() and when useEffect() is better.
React, TypeScript, and TDD
React Advanced Conference 2021React Advanced Conference 2021
174 min
React, TypeScript, and TDD
Top Content
Featured WorkshopFree
Paul Everitt
Paul Everitt
ReactJS is wildly popular and thus wildly supported. TypeScript is increasingly popular, and thus increasingly supported.

The two together? Not as much. Given that they both change quickly, it's hard to find accurate learning materials.

React+TypeScript, with JetBrains IDEs? That three-part combination is the topic of this series. We'll show a little about a lot. Meaning, the key steps to getting productive, in the IDE, for React projects using TypeScript. Along the way we'll show test-driven development and emphasize tips-and-tricks in the IDE.
Designing Effective Tests With React Testing Library
React Summit 2023React Summit 2023
151 min
Designing Effective Tests With React Testing Library
Top Content
Featured Workshop
Josh Justice
Josh Justice
React Testing Library is a great framework for React component tests because there are a lot of questions it answers for you, so you don’t need to worry about those questions. But that doesn’t mean testing is easy. There are still a lot of questions you have to figure out for yourself: How many component tests should you write vs end-to-end tests or lower-level unit tests? How can you test a certain line of code that is tricky to test? And what in the world are you supposed to do about that persistent act() warning?
In this three-hour workshop we’ll introduce React Testing Library along with a mental model for how to think about designing your component tests. This mental model will help you see how to test each bit of logic, whether or not to mock dependencies, and will help improve the design of your components. You’ll walk away with the tools, techniques, and principles you need to implement low-cost, high-value component tests.
Table of contents- The different kinds of React application tests, and where component tests fit in- A mental model for thinking about the inputs and outputs of the components you test- Options for selecting DOM elements to verify and interact with them- The value of mocks and why they shouldn’t be avoided- The challenges with asynchrony in RTL tests and how to handle them
Prerequisites- Familiarity with building applications with React- Basic experience writing automated tests with Jest or another unit testing framework- You do not need any experience with React Testing Library- Machine setup: Node LTS, Yarn
Master JavaScript Patterns
JSNation 2024JSNation 2024
145 min
Master JavaScript Patterns
Featured Workshop
Adrian Hajdin
Adrian Hajdin
During this workshop, participants will review the essential JavaScript patterns that every developer should know. Through hands-on exercises, real-world examples, and interactive discussions, attendees will deepen their understanding of best practices for organizing code, solving common challenges, and designing scalable architectures. By the end of the workshop, participants will gain newfound confidence in their ability to write high-quality JavaScript code that stands the test of time.
Points Covered:
1. Introduction to JavaScript Patterns2. Foundational Patterns3. Object Creation Patterns4. Behavioral Patterns5. Architectural Patterns6. Hands-On Exercises and Case Studies
How It Will Help Developers:
- Gain a deep understanding of JavaScript patterns and their applications in real-world scenarios- Learn best practices for organizing code, solving common challenges, and designing scalable architectures- Enhance problem-solving skills and code readability- Improve collaboration and communication within development teams- Accelerate career growth and opportunities for advancement in the software industry
Integrating LangChain with JavaScript for Web Developers
React Summit 2024React Summit 2024
92 min
Integrating LangChain with JavaScript for Web Developers
Featured Workshop
Vivek Nayyar
Vivek Nayyar
Dive into the world of AI with our interactive workshop designed specifically for web developers. "Hands-On AI: Integrating LangChain with JavaScript for Web Developers" offers a unique opportunity to bridge the gap between AI and web development. Despite the prominence of Python in AI development, the vast potential of JavaScript remains largely untapped. This workshop aims to change that.Throughout this hands-on session, participants will learn how to leverage LangChain—a tool designed to make large language models more accessible and useful—to build dynamic AI agents directly within JavaScript environments. This approach opens up new possibilities for enhancing web applications with intelligent features, from automated customer support to content generation and beyond.We'll start with the basics of LangChain and AI models, ensuring a solid foundation even for those new to AI. From there, we'll dive into practical exercises that demonstrate how to integrate these technologies into real-world JavaScript projects. Participants will work through examples, facing and overcoming the challenges of making AI work seamlessly on the web.This workshop is more than just a learning experience; it's a chance to be at the forefront of an emerging field. By the end, attendees will not only have gained valuable skills but also created AI-enhanced features they can take back to their projects or workplaces.Whether you're a seasoned web developer curious about AI or looking to expand your skillset into new and exciting areas, "Hands-On AI: Integrating LangChain with JavaScript for Web Developers" is your gateway to the future of web development. Join us to unlock the potential of AI in your web projects, making them smarter, more interactive, and more engaging for users.