3 ms·

brabel that's fair, I also like simple things btw. Can you please share your doc site, so that I can at least know what kind of docs experience you are buildin

brabel that's fair, I also like simple things btw. Can you please share your doc site, so that I can at least know what kind of docs experience you are building? Tailwind is not something we support atm, and when we'll do it will be optional. The only choices you cannot opt-out are: Node.js, React, CSS, JavaScript, Markdown/MDX. The rest is all optional and provided as plugins. You don't need to use TS nor Tailwind, but isn't it nice to be able to use those if you want to? For sure you can hand write a top-notch doc site using html, css and vanilla JS. You can also write all your programs in assemble/bytecode/machine code if you want, and similarly they could potentially make these programs faster than their C++, Rust, Java equivalent. I doubt this is a great idea, but in the end you are responsible for your choices. Docusaurus is a tool that will help you achieve the desired result for a lower effort, it's like the Pareto principle. > Well, I can copy your theme into my hand-written HTML which then wrapps the markdown content I wrote... Well, it doubt it's as easy as you think it is. We took great care of accessibility, interactivity and many other things that you'd have a hard time copy/pasting. I wonder if you have looked at any Docusaurus site. Here's a good example: https://www.courier.com/docs/reference/send/message/ https://www.courier.com/docs/reference/send/message/ To me, even if technically it is possible to reproduce such site in Vanilla JS, it would take me a lot of time to do so. Docusaurus only helps you save time to achieve that experience. > One thing I have difficulty generating is a search toolbox... but that's only because I haven't added the "feature" yet... and as I said: I like to keep things simple. So you want search or not, it's not clear to me? Because if you don't, then users can't search and that may be a UX/DX problem, and if you do, then your stack becomes more and more complex and you invest a lot of time building it as you pile features one after the other. You could as well bet on Docusaurus in the first place, and use our search plugins to get search for free. TLDR: if you value your time and plan to scale a bit your doc, Docusaurus is a great choice to me, even if it looks overly engineering for your initial need. Now you can definitively get a similar experience with vanilla JS, if you are willing to invest a lot of hours to make everything work. And there are things that Docusaurus do that you may not even notice by simply looking at the UI, such as make your doc very accessible or providing good SEO by default.

brabel 4y ago
This account is my "anonymous" account, so I can't give you an example of what docs I can create myself... but docs systems I like include asciidoctor[1] and mdbook [2]. Though I find that even those are overkill for my hobby projects at least ... professionally, I prefer to use them anyway because of support/updates and to leave something others can manage themselves later. > Now you can definitively get a similar experience with vanilla JS This comment seems to show we come from very different worlds. Why do you believe you need JS to create documentation?? Have you tried writing HTML/CSS without any generator/JS/tools? It's actually pretty easy... Documentation is mostly static, which HTML/CSS was designed to create... and if you want to add a little interactivity here and there (e.g. run this code live) you can just embed something like Codepen.io or even, yes, vanilla JS if really necessary. I do agree your tool is quite amazing... the fact it takes care of verifying crosslinking, for example, is great... but I hope you do understand that you're using a heavy-weight tool to do something that's usually pretty basic (or maybe you think of docs as something much, much more advanced than what I think of - like the Rust Docs to me are a good example of great docs and I can't even think of why anyone would need anything more advanced - I think you would find that far from advanced? Othewise, you'd agree you can easily write that by hand with HTML/CSS and a little scripting around perhaps to do crosslinking, md-to-html conversion and simple stuff like that). [1] https://docs.asciidoctor.org/asciidoctor/latest/ https://docs.asciidoctor.org/asciidoctor/latest/ [2] https://rust-lang.github.io/mdBook/ https://rust-lang.github.io/mdBook/
- slorber 4y ago
  > I like include asciidoctor[1] and mdbook [2]. Though I find that even those are overkill for my hobby projects at least ... That's one thing: Docusaurus is not necessary just for hobby projects where the doc only exists for yourself and a few users. It can be used for hobby project but it can also scale for much larger projects where the doc is a critical part of the success of the project, and where the company behind is willing to invest thousands of dollars to have a really great doc. For example, the doc of React-Native is critical for React-Native success: https://reactnative.dev https://reactnative.dev > I prefer to use them anyway because of support/updates and to leave something others can manage themselves later. If you have a small project, you can also use Docusaurus in a very simple way, and stick to our stock template (which looks like this: https://tutorial.docusaurus.io/ https://tutorial.docusaurus.io/) The only thing you'll need is to leave a folder of Markdown files to your colleagues, that's all. I have planned to add a very simple CLI on top of Docusaurus to make it even easier: just run "npx yolodoc ./my-md-docs-folder" and it will build your simple Docusaurus site => No need to install anything, know that it's using React/MDX/TS or whatever: the only thing you'd need is to have Node.js installed (which is not more complicated to install than Python or Ruby btw) > This comment seems to show we come from very different worlds. Why do you believe you need JS to create documentation?? I don't believe that. I believe you can do everything by hand but at some point when you have thousands of docs pages, you also need to be productive and fall into the pit of success by adopting tools that streamline the docs authoring experience for your doc team. Do you prefer throwing 1000h of your time on your home made solution, or just use Docusaurus and save time, and get a better result for something like 200h? => That's the value proposition of Docusaurus. Also note that for some accessibility details, you do need to have some JS because using just HTML has its limit. Docusaurus takes great care of accessibility concerns by default for you: progressive enhancement, skip-to-content, aria labels, keyboard navigation, focus rings, semantic html... > and if you want to add a little interactivity here and there (e.g. run this code live) you can just embed something like Codepen.io or even, yes, vanilla JS if really necessary. There are many places where you probably want JS in your doc site: collapsible categories, search, tabs to switch SDK languages, mobile drawer menu etc... Using just HTML has its limit. Now Docusaurus doesn't just bring interactivity to the "layout" but also inside the docs. This makes it possible to build interactive documentation where the experience is natively more "playful" https://docusaurus.io/docs/markdown-features/react https://docusaurus.io/docs/markdown-features/react https://docusaurus.io/docs/markdown-features/code-blocks#interactive-code-editor https://docusaurus.io/docs/markdown-features/code-blocks#int... Using Codepen.io or CodeSandbox inside your doc leads to a subpar experience to what we want to provide with Docusaurus. Those embeds are not native to the website and require a heavy iframe to load. Also the demo code you maintain would be saved in a separate system which makes long term maintainance more complicated than to colocate example code with actual docs rendering those. Using an iframe can also reach some sandboxing limits due to browser securities for certain use-cases. If you are going to build an API client for your REST API (ie have a Stripe-like API docs experience), I doubt you'd be able to get a great DX with iframe embeds. Instead you want the API client to be native, load fast, and integrate nicely with the rest of your docs site layout. See for example this Courier API client using Docusaurus: the code sample has a sticky positioning and always remains visible: https://www.courier.com/docs/reference/send/message/ https://www.courier.com/docs/reference/send/message/ It would simply be impossible to get this better UX with an iframe embed. --- > I do agree your tool is quite amazing... the fact it takes care of verifying crosslinking, for example, is great... Thanks ;) > but I hope you do understand that you're using a heavy-weight tool to do something that's usually pretty basic (or maybe you think of docs as something much, much more advanced than what I think of - like the Rust Docs to me are a good example of great docs and I can't even think of why anyone would need anything more advanced - I think you would find that far from advanced? I think I didn't explain very well, but most of the "complex stack" of Docusaurus is not directly exposed to you. Similarly, do you really care about which libs MdBook is using under the hood? Would you say "MdBook is overly complicated because it's using XYZ as a dependency!"? Docusaurus used React, MDX, Node.js, Remark, Webpack, TypeScript, Infima... All those buzzwords are internal implementation details, and you do not really need to care about them: just write markdown files! Is one of those 2 commands really more complicated than the other? "mdbook serve --open" vs "docusaurus start" Because in both cases, it's what it takes to use the tool: just start it, and focus on writing good content in Markdown files. Docusaurus can do much more than that, but you can stick to the simpler workflow if you have basic needs. Just watch this 60sec video demo and see how simple it is: https://twitter.com/leeerob/status/1554211061284364290 https://twitter.com/leeerob/status/1554211061284364290 > Othewise, you'd agree you can easily write that by hand with HTML/CSS and a little scripting around perhaps to do crosslinking, md-to-html conversion and simple stuff like that). I totally agree with that. I just feel it would be more time consuming than using a dedicated doc tool that already solved this problem for you. It can by MdBook, Docusaurus or whatever else you like. But at the end of the day, you are free to use whatever tool is good for your use case. I do believe that the default Docusaurus output provide a better UX than the MdBook output, but it is a matter of personal taste I guess. And it's not more complicated: you just give it Markdown files and run a CLI command to build the site. The only major difference for you, as a docs user with relatively simple needs, is that you have to install Node.js instead of Cargo.

brabel 4y ago

This account is my "anonymous" account, so I can't give you an example of what docs I can create myself... but docs systems I like include asciidoctor[1] and mdbook [2]. Though I find that even those are overkill for my hobby projects at least ... professionally, I prefer to use them anyway because of support/updates and to leave something others can manage themselves later. > Now you can definitively get a similar experience with vanilla JS This comment seems to show we come from very different worlds. Why do you believe you need JS to create documentation?? Have you tried writing HTML/CSS without any generator/JS/tools? It's actually pretty easy... Documentation is mostly static, which HTML/CSS was designed to create... and if you want to add a little interactivity here and there (e.g. run this code live) you can just embed something like Codepen.io or even, yes, vanilla JS if really necessary. I do agree your tool is quite amazing... the fact it takes care of verifying crosslinking, for example, is great... but I hope you do understand that you're using a heavy-weight tool to do something that's usually pretty basic (or maybe you think of docs as something much, much more advanced than what I think of - like the Rust Docs to me are a good example of great docs and I can't even think of why anyone would need anything more advanced - I think you would find that far from advanced? Othewise, you'd agree you can easily write that by hand with HTML/CSS and a little scripting around perhaps to do crosslinking, md-to-html conversion and simple stuff like that). [1] https://docs.asciidoctor.org/asciidoctor/latest/ https://docs.asciidoctor.org/asciidoctor/latest/ [2] https://rust-lang.github.io/mdBook/ https://rust-lang.github.io/mdBook/

slorber 4y ago
> I like include asciidoctor[1] and mdbook [2]. Though I find that even those are overkill for my hobby projects at least ... That's one thing: Docusaurus is not necessary just for hobby projects where the doc only exists for yourself and a few users. It can be used for hobby project but it can also scale for much larger projects where the doc is a critical part of the success of the project, and where the company behind is willing to invest thousands of dollars to have a really great doc. For example, the doc of React-Native is critical for React-Native success: https://reactnative.dev https://reactnative.dev > I prefer to use them anyway because of support/updates and to leave something others can manage themselves later. If you have a small project, you can also use Docusaurus in a very simple way, and stick to our stock template (which looks like this: https://tutorial.docusaurus.io/ https://tutorial.docusaurus.io/) The only thing you'll need is to leave a folder of Markdown files to your colleagues, that's all. I have planned to add a very simple CLI on top of Docusaurus to make it even easier: just run "npx yolodoc ./my-md-docs-folder" and it will build your simple Docusaurus site => No need to install anything, know that it's using React/MDX/TS or whatever: the only thing you'd need is to have Node.js installed (which is not more complicated to install than Python or Ruby btw) > This comment seems to show we come from very different worlds. Why do you believe you need JS to create documentation?? I don't believe that. I believe you can do everything by hand but at some point when you have thousands of docs pages, you also need to be productive and fall into the pit of success by adopting tools that streamline the docs authoring experience for your doc team. Do you prefer throwing 1000h of your time on your home made solution, or just use Docusaurus and save time, and get a better result for something like 200h? => That's the value proposition of Docusaurus. Also note that for some accessibility details, you do need to have some JS because using just HTML has its limit. Docusaurus takes great care of accessibility concerns by default for you: progressive enhancement, skip-to-content, aria labels, keyboard navigation, focus rings, semantic html... > and if you want to add a little interactivity here and there (e.g. run this code live) you can just embed something like Codepen.io or even, yes, vanilla JS if really necessary. There are many places where you probably want JS in your doc site: collapsible categories, search, tabs to switch SDK languages, mobile drawer menu etc... Using just HTML has its limit. Now Docusaurus doesn't just bring interactivity to the "layout" but also inside the docs. This makes it possible to build interactive documentation where the experience is natively more "playful" https://docusaurus.io/docs/markdown-features/react https://docusaurus.io/docs/markdown-features/react https://docusaurus.io/docs/markdown-features/code-blocks#interactive-code-editor https://docusaurus.io/docs/markdown-features/code-blocks#int... Using Codepen.io or CodeSandbox inside your doc leads to a subpar experience to what we want to provide with Docusaurus. Those embeds are not native to the website and require a heavy iframe to load. Also the demo code you maintain would be saved in a separate system which makes long term maintainance more complicated than to colocate example code with actual docs rendering those. Using an iframe can also reach some sandboxing limits due to browser securities for certain use-cases. If you are going to build an API client for your REST API (ie have a Stripe-like API docs experience), I doubt you'd be able to get a great DX with iframe embeds. Instead you want the API client to be native, load fast, and integrate nicely with the rest of your docs site layout. See for example this Courier API client using Docusaurus: the code sample has a sticky positioning and always remains visible: https://www.courier.com/docs/reference/send/message/ https://www.courier.com/docs/reference/send/message/ It would simply be impossible to get this better UX with an iframe embed. --- > I do agree your tool is quite amazing... the fact it takes care of verifying crosslinking, for example, is great... Thanks ;) > but I hope you do understand that you're using a heavy-weight tool to do something that's usually pretty basic (or maybe you think of docs as something much, much more advanced than what I think of - like the Rust Docs to me are a good example of great docs and I can't even think of why anyone would need anything more advanced - I think you would find that far from advanced? I think I didn't explain very well, but most of the "complex stack" of Docusaurus is not directly exposed to you. Similarly, do you really care about which libs MdBook is using under the hood? Would you say "MdBook is overly complicated because it's using XYZ as a dependency!"? Docusaurus used React, MDX, Node.js, Remark, Webpack, TypeScript, Infima... All those buzzwords are internal implementation details, and you do not really need to care about them: just write markdown files! Is one of those 2 commands really more complicated than the other? "mdbook serve --open" vs "docusaurus start" Because in both cases, it's what it takes to use the tool: just start it, and focus on writing good content in Markdown files. Docusaurus can do much more than that, but you can stick to the simpler workflow if you have basic needs. Just watch this 60sec video demo and see how simple it is: https://twitter.com/leeerob/status/1554211061284364290 https://twitter.com/leeerob/status/1554211061284364290 > Othewise, you'd agree you can easily write that by hand with HTML/CSS and a little scripting around perhaps to do crosslinking, md-to-html conversion and simple stuff like that). I totally agree with that. I just feel it would be more time consuming than using a dedicated doc tool that already solved this problem for you. It can by MdBook, Docusaurus or whatever else you like. But at the end of the day, you are free to use whatever tool is good for your use case. I do believe that the default Docusaurus output provide a better UX than the MdBook output, but it is a matter of personal taste I guess. And it's not more complicated: you just give it Markdown files and run a CLI command to build the site. The only major difference for you, as a docs user with relatively simple needs, is that you have to install Node.js instead of Cargo.