Why do you need a docs?

People often ask me, do we really need a framework to build docs sites? Well, You don't.

Documentation sites are so important in software development, an internal docs for developers in your company to understand the architecture, a docs for frameworks, a docs for web standards...

Building docs is simple, but difficult.

There are so many paradigms to build a docs, but writing a beginner-friendly docs could be difficult. As a result, people tends to use powerful docs frameworks, making the docs site interactive and straightforward.

Over-Engineered

For the docs of a small library/API service, you probably don't need to setup a Next.js site and spend time writing your site. Neither Nextra nor Fumadocs could be better than GitHub wiki and Swagger docs in this case.

They offer a good, descent UI, basic functionalities, and a proper workflow of authoring docs. The DX is good enough, I can't think of a reason to switch to a full-powered docs framework just to make your docs looks fancy.

I'll just recommend writing your docs in markdown, make it accessible on your GitHub repository.

Why Framework?

Now you may wonder, why major services and frameworks have their own docs sites built with docs frameworks?

Of course, Usually using things like GitHub Wiki is adequate, but it is not always true. Let's take Component Library for example, you cannot showcase your components with Markdown. You will constantly find an ordinary Markdown document lacks of capability and flexibility.

Documentation frameworks aim to solve this problem, with the ability to integrate with major libraries like React.js and Vue.js. Good examples are Vitepress, Mintlify and Nextra - They made writing a docs more convenient and effective, while offering a better, dedicated experience to readers.

For anything more than a simple library or API service, it is worth a try.

Reinvent the Wheels

I would never recommend building a "custom docs site" on your own, without a proper docs framework. Despite the Don't re-invent the wheels principle, your hand-made docs site actually takes way more efforts to make it descent.

1. Document Search
2. A user-friendly navigation experience
3. Reading experience
4. UI/UX Design

Implementing them properly already sounds nerve-racking, right?

The docs itself, is definitely not your first priority. Never should you spend your precious time re-inventing the wheels - it isn't worth.

From my perspective, I'd rather use GitHub Wiki than re-inventing the wheels. Why don't pick a descent solution? It saves your indispensable time, and help reducing the shitty docs sites on the internet.

What we focus at Fumadocs?

I personally value reading experience more than a fancy eye-catching UI. You may notice, we do not have animations everywhere, and we avoided many fancy designs.

Fanciness of UI should stay only in landing page, a docs site should focus on content. Navigation elements are helpers to browse your site, never should they take up too much space on the screen.

One thing I hated the most is the design of two sidebars, it is confusing and meaningless. You can just organize all items to a single, clean sidebar, but people instead added two hamburger buttons to the navbar.

My favourite docs site is still Linear docs, looks good and simple.

Conclusion

1. You don't need a full-powered docs framework for a small library
2. Don't make a docs site on your own, use a proper docs framework
3. Fumadocs focuses on reading experience
4. You should focus on content, too