3 ms·

I think it depends on your end users. If you're building a product for devs, personally, I think it's worth investing in a great docs experience and more 'advan

I think it depends on your end users. If you're building a product for devs, personally, I think it's worth investing in a great docs experience and more 'advanced' features. Docs are going to be one of your most used interfaces. But you should make sure that making docs 'pretty' isn't detracting from usability. If you're making internal docs, then ya, I agree with you, keep it dead simple.

slorber 4y ago
> Unless you're spinning up a documentation team with engineering resources, you probably want Docusaurus! > Rachel Nabors, Former ReactJS & React-Native docs manager > https://twitter.com/rachelnabors/status/1452697991039660038 https://twitter.com/rachelnabors/status/1452697991039660038 Actually I don't consider Docusaurus as a real investment. altough as a non-Node.js/React dev all this might sound complex, but this is actually the basic stack for many frontend devs today, not something very fancy. Investing in your docs mean assembling a tech team for a long effort to build a first class experience. I believe you can achieve something almost as good as a full team by having just 1 engineer working on your Docusaurus doc a few hours per week. > If you're making internal docs, then ya, I agree with you, keep it dead simple. Internal docs also deserve a great DX. You can use Docusaurus for internal docs, and use our stock template to get started in a few minutes: just write markdown files. We have been reported heavy usage of Docusaurus at Microsoft and LinkedIn for internal documentations for example. This is what our stock template look out of the box: https://tutorial.docusaurus.io/ https://tutorial.docusaurus.io/ You don't have to do anything to have this DX: just write md files. Maybe you can already feed Docuaurus with your existing md files, and it will just work without any change.

slorber 4y ago

> Unless you're spinning up a documentation team with engineering resources, you probably want Docusaurus! > Rachel Nabors, Former ReactJS & React-Native docs manager > https://twitter.com/rachelnabors/status/1452697991039660038 https://twitter.com/rachelnabors/status/1452697991039660038 Actually I don't consider Docusaurus as a real investment. altough as a non-Node.js/React dev all this might sound complex, but this is actually the basic stack for many frontend devs today, not something very fancy. Investing in your docs mean assembling a tech team for a long effort to build a first class experience. I believe you can achieve something almost as good as a full team by having just 1 engineer working on your Docusaurus doc a few hours per week. > If you're making internal docs, then ya, I agree with you, keep it dead simple. Internal docs also deserve a great DX. You can use Docusaurus for internal docs, and use our stock template to get started in a few minutes: just write markdown files. We have been reported heavy usage of Docusaurus at Microsoft and LinkedIn for internal documentations for example. This is what our stock template look out of the box: https://tutorial.docusaurus.io/ https://tutorial.docusaurus.io/ You don't have to do anything to have this DX: just write md files. Maybe you can already feed Docuaurus with your existing md files, and it will just work without any change.