4 ms·

With Docusaurus we are looking to compete with top notch documentations, not simple ones. The goal is not only to get some html files online but also to great

With Docusaurus we are looking to compete with top notch documentations, not simple ones. The goal is not only to get some html files online but also to great a first-class experience for the end user. Do you truly believe that your home-made setup would be sufficient to output a top-notch doc site? Really curious to see what kind of site your setup produce, can you share a live url so that we can compare? Docusaurus v2 has a site showcase with many great looking sites: https://docusaurus.io/showcase https://docusaurus.io/showcase Many companies using it: Supabase, Redis, Figma, Ionic, Snapchat, LinkedIn, Microsoft, Shopify, Tauri... I doubt these companies would be satisfied with a home-made setup like yours. If you don't have advanced needs, you could as well just publish md files on GitHub?

nindalf 4y ago
I wouldn’t worry too much about that comment. The top comment is very much in keeping with the HN tradition of trashing others’ work without fully understanding the use case. My favourite HN comment went like “For a Linux user, you can already build such a system yourself quite trivially by getting an FTP account, mounting it locally with curlftpfs, and then using SVN or CVS on the mounted filesystem.” (https://news.ycombinator.com/item?id=8863 https://news.ycombinator.com/item?id=8863) Fortunately the person this was addressed to continued building Dropbox.
- slorber 4y ago
  ahah, I welcome all comments, haters are a good source of engagement ;)
taffit 4y ago
Well, there's a tool for every task and yours in this case might be too overblown for the simple task that the user is trying to solve. No need to compare it to the use at bigger companies and organizations. No need to either get arrogant or stroppy. Just because a user doesn't use your tool, she is not a hater, neither. Sound a bit like "But mine is better/bigger/shinier than yours!" to me. Keep cool.
- slorber 4y ago
  Well, the op was quite offensive in the first place > this is so incredibly over-engineered it's comical to me. Isn't it fair that I defend the tool I work on after reading such comment? The op can stick with its original tool and that's perfectly fine to me. Indeed Docusaurus might be overkill for many simple use-cases. Does it mean it's over-engineered? Well, that's worth discussing. Some companies really need the features we provide. Can you build something as advanced as some of the existing Docusaurus sites we showcase, using a simpler stack? That's an interesting discussion to have, but share some links.
  - taffit 4y ago
    Well, I don't see the offensive part here. As you say it yourself: "It might be overkill for many simple use-cases." Period. No need to jump into every thread where a user says that it is just too much for her use case, and you asking for links to compare the output (as you did with me as well?). Just be happy with what you created and the showcases prove the demand for it. So?
    - slorber 4y ago
      Well, we don't have at all the same definition of what "offensive" means then. > where a user says that it is just too much for her use case That's not at all what the op said, just a 2nd reminder: > > this is so incredibly over-engineered it's comical to me. The op said it's over-engineered, in general, not for her use-case --- I am happy with the result and I won't be affected too much by comments from people that criticize what we've built without giving it a try. Now I keep the right to defend the tool when it's criticized this way.
brabel 4y ago
Don't get me wrong... I just like simple things, and this is definitely not simple, so not to my taste... I am sure the majority of people out there will love support for React, TailCSS or whatever else this supports... But I do believe I am able to write top notch documentation by simply being good at HTML/CSS... because that's what it really goes down to in the end?! How does Docusaurus make things pretty? By using themes? Well, I can copy your theme into my hand-written HTML which then wrapps the markdown content I wrote... I don't think end users would notice any difference whatsoever? 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.
- slorber 4y ago
  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.

nindalf 4y ago

I wouldn’t worry too much about that comment. The top comment is very much in keeping with the HN tradition of trashing others’ work without fully understanding the use case. My favourite HN comment went like “For a Linux user, you can already build such a system yourself quite trivially by getting an FTP account, mounting it locally with curlftpfs, and then using SVN or CVS on the mounted filesystem.” (https://news.ycombinator.com/item?id=8863 https://news.ycombinator.com/item?id=8863) Fortunately the person this was addressed to continued building Dropbox.

slorber 4y ago
ahah, I welcome all comments, haters are a good source of engagement ;)

taffit 4y ago

Well, there's a tool for every task and yours in this case might be too overblown for the simple task that the user is trying to solve. No need to compare it to the use at bigger companies and organizations. No need to either get arrogant or stroppy. Just because a user doesn't use your tool, she is not a hater, neither. Sound a bit like "But mine is better/bigger/shinier than yours!" to me. Keep cool.

slorber 4y ago
Well, the op was quite offensive in the first place > this is so incredibly over-engineered it's comical to me. Isn't it fair that I defend the tool I work on after reading such comment? The op can stick with its original tool and that's perfectly fine to me. Indeed Docusaurus might be overkill for many simple use-cases. Does it mean it's over-engineered? Well, that's worth discussing. Some companies really need the features we provide. Can you build something as advanced as some of the existing Docusaurus sites we showcase, using a simpler stack? That's an interesting discussion to have, but share some links.
- taffit 4y ago
  Well, I don't see the offensive part here. As you say it yourself: "It might be overkill for many simple use-cases." Period. No need to jump into every thread where a user says that it is just too much for her use case, and you asking for links to compare the output (as you did with me as well?). Just be happy with what you created and the showcases prove the demand for it. So?
  - slorber 4y ago
    Well, we don't have at all the same definition of what "offensive" means then. > where a user says that it is just too much for her use case That's not at all what the op said, just a 2nd reminder: > > this is so incredibly over-engineered it's comical to me. The op said it's over-engineered, in general, not for her use-case --- I am happy with the result and I won't be affected too much by comments from people that criticize what we've built without giving it a try. Now I keep the right to defend the tool when it's criticized this way.

brabel 4y ago

Don't get me wrong... I just like simple things, and this is definitely not simple, so not to my taste... I am sure the majority of people out there will love support for React, TailCSS or whatever else this supports... But I do believe I am able to write top notch documentation by simply being good at HTML/CSS... because that's what it really goes down to in the end?! How does Docusaurus make things pretty? By using themes? Well, I can copy your theme into my hand-written HTML which then wrapps the markdown content I wrote... I don't think end users would notice any difference whatsoever? 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.

slorber 4y ago
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.