DEV Community


What are you using for your documentation?

Martin Belev
Lead Software Developer at The Stars Group, JS/TS/React, former maths competitor, fitness and cooking enthusiast
・1 min read

Hi everyone,

I am sure there is no "best" tool for it but what are your recommendations for documentation. It should support MDX.

  • Gatsby has some nice themes for documentation
  • there is Docz which is built on top of Gatsby
  • Dokz which is powered by NextJS
  • I am sure there are a lot more tools out there

What is your preferred choice? What would you use if you have to start writing documentation today?

Discussion (22)

kant312 profile image
Quentin Delcourt

VuePress is an efficient tool for writing documentation:

cguttweb profile image

Seconded I asked a similar question and I have decided to use this for my own personal docs as I wanted something Vue based.

coreybutler profile image
Corey Butler

Personally, I feel like the industry needs a new take on docs in general. We're rethinking the process of using docs, through basically docs as a data source. We're focusing on documenting Go libs to start (because it's low hanging fruit), but I've made alot of headway on a JS doc generator as well ( By focusing on the production of data instead of HTML, we'll be able to generate pretty/unified docs in just about any format.

bobbyiliev profile image
Bobby Iliev

I really like LaRecipe

I actually wrote a post about it a few weeks ago on DEV:

Write gorgeous documentation for your products using Markdown inside your Laravel app

remotesynth profile image
Brian Rinaldi

I wrote up a whole post on this topic that covers some options (all Jamstack focused).

For docs, I prefer something like Hugo as I really don't see the need to have a React-based frontend on it since the primary goal is just to serve up static content. I like Hugo for this because it compiles incredibly fast and docs sites can get large.

martinbelev profile image
Martin Belev Author

Thank you for sharing, I will check it out.

mskog profile image
Magnus Skog

At work we use Hugo with the Learn theme. It works really well but it is a bit of a pain to have to commit code to update the documentation.

At home I use Notion for just about everything, including documentation.

_garybell profile image
Gary Bell

I'm currently using a folder called "documentation" and a bunch of .md files.

I figure the documentation is then with the source code when the developer is working on it, and therefore doesn't need an internet connection to work.

It does the job for now, but I want to look at alternatives at some point. I want it to be part of source control so I can add items to the code reviews to document certain things.

gsto profile image
Glenn Stovall

Is this for internal documentation or external facing? For internal we're using Github wiki.

martinbelev profile image
Martin Belev Author

It will be for internal usage. We have and are using Confluence but things are not as we want them to be in there. So we are looking for other solutions.

As we are using React, most probably going to use a tech that is React based. For now Gatsby seems like a very decent option for the things that we want.

gsto profile image
Glenn Stovall

Could you tell me more about "things are not as we want them to be in there."?

Thread Thread
martinbelev profile image
Martin Belev Author

Confluence has been for a long time, a lot of people are using it and it has all kind of information.

Maybe a little more about what we are trying to achieve (or at least some of the most important pieces) so that it can be more understandable why Confluence is not the best thing for us:

  • We would like to have the news docs in more structured way which will be more related to the project itself, not having everything in there.
  • From our backend we got JSON API documentation which is going to be presented in the new docs in a prettier way than JSON format.
  • We want to have some kind of integration with our components in Storybook.

This being the case, Confluence doesn’t seem like the best place to put everything. And I believe it is not possible to have all of the needed things in there to be honest.

martinbelev profile image
Martin Belev Author

I would like to thank you all for joining the discussion.

Our investigation is over and we made a decision. We are going to use Gatsby with Docz extended theme.

A couple of points which led us to this decision:

  • it is React based and this fits well into our project because we are using React
  • it is not opinionated and full of conventions which gives flexibility so that we can customise however we want
  • it is evolving quickly and the community is great
  • great performance
  • React documentation is built with Gatsby which was a good indicator for us
pushkar8723 profile image
Pushkar Anand anyone?

scriptautomate profile image
Derek Ardolf • Edited

I've tried tools like Jekyll and Hugo, both of which I still use for blogs, but they didn't meet requirements for certain documentation projects.

Now I'm a huge fan of Sphinx: which is open-source, and doesn't require any licensing. It can use Markdown or reStructuredText (rST). rST has become my go-to, and has seemed capable of doing more things within Sphinx out-of-box.

Sphinx can be used for general documentation, but can also automatically generate documentation from Python docstrings in code repositories, Javascript projects (thanks to efforts by Mozilla), and even Go or .NET with other extensions: all by pulling from comment blocks to make use of documentation from within the code base itself.

If arguments/options are already being documented within the code, then why not extract it to add to the separately written docs?

Automation can be introduced to documentation around things like spelling and URL link validation.

Automation pipelines can include jobs that generate PDFs (Sphinx uses things like LaTeX/LuaTex/XeTeX/etc.) and even ePUB files from the documentation, too, rather than just the HTML static site.

I'm thinking of creating some quickstart projects that use GitLab/GitHub Pages, and GitLab CI / GitHub Actions for automatically building and deploying websites in a GitOps fashion. I'll be including PDF generation as part of the pipelines.

I do have some biases here, though, like using Python as my tool of choice. Sphinx is python-based. I've also been wanting to create tooling that can generate a blog but also an ebook/PDF from blog contents. That, and even print-ready PDFs with proper formatting for print-on-demand (POD) style printers like KDP. I also have many projects that cross-reference each other, so that idea of importing compatible rst files from other source repos was ideal.

jldohmann profile image

Sphinx is something I've been meaning to check out! A lot of open source projects use it, so it seems useful to know how it works when contributing to a project.

I'm thinking of creating some quickstart projects that use GitLab/GitHub Pages, and GitLab CI / GitHub Actions for automatically building and deploying websites in a GitOps fashion. I'll be including PDF generation as part of the pipelines.

I would be really interested in reading a write up on how you do this, if you ever have the time!

brpaz profile image
Bruno Paz

I like Vuepress and MkDocs with Material Theme.

For API documentation, Redoc.

bouzaf profile image

I just recently used OpenAPI 3 with ReDoc (redoc-cli), looks pretty nice.

jbroomer profile image

Docusaurus! So much out-of-the-box capability and very straightforward however, it also has the option to customize and add plugins.

bindian0509 profile image
भरत वर्मा (BHARAT V)

Nothing can beat speca

sayjava profile image
Raymond Ottun Is decent. A very quick and dirty way to get started

thokuest profile image
Thomas Küstermann

Happily using Antora and not looking back. Documentation is written in Asciidoc, though.