3 ms·
You don’t need it to write docs. But, as someone who’s worked in a relatively large documentation org… it’s nice to have a stable, extensible base that you can
by vanilla_nut 4y ago
You don’t need it to write docs. But, as someone who’s worked in a relatively large documentation org… it’s nice to have a stable, extensible base that you can extend consistently across multiple docs sites. It’s ideal to have a similar look and feel, but the flexibility to tweak that for each product.
Basic docs sites can literally just be HTML. But the more you maintain them, the more you want to experiment with novel methods of documentation (think: interactive consoles, new methods of styling guides and tutorials like Apple’s SwiftUI docs, or even new methods of segmenting content within a single docs site (SDK and versioning selectors, anyone?))… eventually, simple tools will hold you back. Or you’ll end up building an unmaintainable nightmare on top of a simple tool. In those cases, it’s nice to use a “batteries included” product so you don’t have to write all of that infrastructure yourself.
For personal blogs and small docs sites, it’s overkill of course. But in docs land just as in developer land, ICs want to build new skills for their resumes or personal interest.
And, of course… it has a built in dark mode! Harder to find than you’d think.
- slorber 4y agoThanks for the feedback Agree Docusaurus might be overkill for simple docs, however we also made sure the experience for simple usage is great. It comes with file-system routing convention, versioning, accessibility, internationalization, good SEO by default and many useful features that would take time to build in userland... We have many devs using Docusaurus as a portfolio or personal blog, we even have a dedicated showcase tag for that: https://docusaurus.io/showcase?tags=personal https://docusaurus.io/showcase?tags=personal For advanced needs, like multi-sdk support, we get you covered. Site with multiple frontend SDKs (React, Angular...): https://docs.dyte.io/react-ui-kit https://docs.dyte.io/react-ui-kit Palo Alto Networks has a dev portal with multiple products using Docusaurus, all sharing similarities but with tweaks per product: - https://xsoar.pan.dev/ https://xsoar.pan.dev/ - https://prisma.pan.dev/ https://prisma.pan.dev/
- swyx 4y agoyes - people should match their docs offerings to the maturity of their project: https://www.swyx.io/documentation-levels https://www.swyx.io/documentation-levels and not dismiss out of hand tools that accommodate a different level than they are currently at.