DEV Community

Mihai
Mihai

Posted on

2 2 1 1 1

What Are Your Favorite Open-Source Documentation Tools?

Documentation is critical for the success of any project, but finding the right open-source tool or library to manage it can be challenging. While there are many options available, I’ve struggled to find one that’s both reliable and suits my project’s needs.

I’m reaching out to gather recommendations:

What open-source tools or libraries do you recommend for creating and hosting documentation?

Are there any lesser-known tools that stand out?

What features do you prioritize in a documentation tool (e.g., versioning, search, customization)?

If you have any suggestions, feel free to share them in the comments. Links to examples or projects using these tools would also be appreciated.

Looking forward to your recommendations.

Top comments (10)

Collapse
 
zethix profile image
Andrey Rusev

Pfeww... tons of things :)

Sort of ... depends - like, if it's docs that should go alongside code (say, on GitHub) - it's pure markdown, or whatever extensions are available. GitHub in particular can also render python notebooks, and we've used that too - example here. It has limitations (like - doesn't want to close the code blocks and only show the output, but still... works somehow...

When docs don't have to live next to code - then it's typically MDX - markdown with some custom visuals - typically because of the need for diagrams, better code blocks, interactivity, etc. These we customize heavily, never really found a documentation platform that fits all of our requirements.

One curious thing on the MDX side - I even started using it (and our customizations) for slides and presentations - with something called Spectacle JS. I just like the markdown and MDX that much. :)

And a (IMHO) little-known tool that helps a lot (cos I'm not really good at writing) - Vale.

I suspect your question is actually more about platforms - the likes of Hugo and Jekyll? What did you try? And what did you not like? I think it's easier to build a website and re-use basic components than it is to adapt these platforms...

Collapse
 
mihaig04 profile image
Mihai

I appreciate the insight! Super useful information 😊.

I've tried Docsify, which was very easy to use, but the problem came when people didn’t follow the guidelines for the docs, for example how to link to pages, display code, and use the different types of Markdown.

It feels like we’ve moved away from the kind of docs where you “code” them yourself or manage the files manually. Now, we’re looking for platforms where you can simply edit the docs and save them.

GitHub Markdown files were good, but we faced similar issues, either people used the wrong formatting or skipped over them entirely.

So, we’re now aiming to limit customizability to ensure more consistency!

Collapse
 
zethix profile image
Andrey Rusev

Now, we’re looking for platforms where you can simply edit the docs and save them.

A-haaa... more like a CMS of some sort? Where you can potentially 'impose' consistency at the moment docs are being written?

Thread Thread
 
mihaig04 profile image
Mihai

Yeah kinda of like a CMS and, of course if we can open source :)

The issue is mainly with how the pages and content are structured. Some people prefer using Markdown with clear headers, code blocks, and well defined paragraphs. Others, however, might dump all the documentation into a single massive file, while some split it across multiple smaller files for better organization.

As a result, you'd think the docs to follow a consistent format, but it rarely does. So normaly you have to slog through just text or sometimes a nice doc. Bit like a lottery 🤣.

Thread Thread
 
zethix profile image
Andrey Rusev

Oh, I see... Well, in my opinion - no paragraphs, no headings - no docs... :) If you get my point... :)

I think Vale.sh might help you with this, but won't be a 'cure-all'... Also perhaps agreeing on a style a Google style guide here and one from Microsoft...

With the exceptions above - nothing free or open source comes to mind at the moment... Even more - somehow it sounds to me you've got a lot of docs (and need for docs perhaps), so, if that's the case I'd probably look for help from professionals...

Collapse
 
pengeszikra profile image
Peter Vivo

Simple markdown file with git versioning.

Collapse
 
mihaig04 profile image
Mihai

Would you store that on the repo itself?

Collapse
 
pengeszikra profile image
Peter Vivo • Edited

yes, that is fine place to every developer read it. Or set the repo publicity to private if don't belong to another one.

Collapse
 
moopet profile image
Ben Sinclair

You've tagged this with #ai - are you specifically thinking about AI tools?

Collapse
 
mihaig04 profile image
Mihai

I heard there are some AI doc tools where they scan yout code base and make docs with that?

Not sure if its a common thing, thats why i tagged this post with ai.

Some comments may only be visible to logged-in visitors. Sign in to view all comments.

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs

👋 Kindness is contagious

Dive into an ocean of knowledge with this thought-provoking post, revered deeply within the supportive DEV Community. Developers of all levels are welcome to join and enhance our collective intelligence.

Saying a simple "thank you" can brighten someone's day. Share your gratitude in the comments below!

On DEV, sharing ideas eases our path and fortifies our community connections. Found this helpful? Sending a quick thanks to the author can be profoundly valued.

Okay