What are you using for public documentation these days?

We are using Docusaurus (https://docusaurus.io/ ).

   - it is easy to configure/customise 
   - looks really great out of the box
   - solid documentation
   - fast

In our case, we just had to change the colors and font. Here is our Docusaurus code if that's helpful: https://github.com/ToolJet/ToolJet/tree/develop/docs and here is the live documentation: https://docs.tooljet.com/

I'm using mkdocs with the material plugins [1]. I'm running it mainly for a Blockchain Education site for my labs from my course, which seems to be fine [2].

I did a fair amount of customization though, so I am running all this as mkdocs plugins, not directly from the materials project.

[1] https://squidfunk.github.io/mkdocs-material/ [2] https://ethereum-blockchain-developer.com

I have an unfinished side project called Documentation Page:

https://documentation.page/

It's "unfinished" because I'd need to integrate payments and do all the accounting on my side (non-trivial as an individual living in Japan), but otherwise it's worked pretty well for my own projects.

It parses your Github Repo to generate the website. You can define your docs as a single readme.md file, a folder called "documentation", or custom configuration otherwise. Some examples hosted by Documentation Page:

- https://statux.dev/: simple single-page docs and website, menu config in https://github.com/franciscop/statux/blob/master/documentati....

- https://react-test.dev/: split into multiple pages, you specify the folder and it'll automatically merge the markdown files. See config https://github.com/franciscop/react-test/blob/master/documen...

- https://crossroad.page/: has an landing page, but that is not officially supported (yet). See the configs in https://github.com/franciscop/crossroad/blob/master/document...

Basic markdown and Sphinx to build into HTML, publishing via github pages. It's an open source project so putting the docs alongside the code just makes sense. Although Sphinx isn't great for my money, it gets the job done.

We use GitBook at Garden (docs.garden.io).

It's zero effort which is important for a small team like ours. Allows us to focus on the content as opposed to bikeshedding design.

Overall I'm happy with the look and feel of things and the support is typically good.

That being said, they recently shipped changes that essentially made the docs site impossibly slow for a few days. They've been working on fixing that and it's better, but not as snappy as before. I also preferred the previous look (it's very similar but the new one is a bit more clunky imo).

We do have a lot of long code examples (YAML reference docs) which I think may contribute to the "sluggishness".

But overall I'd recommend if you want to minimise effort and maintenance. In any case it's easy to give it a spin and see if it works for you.

We (Handsontable) now use VuePress[1] for our docs[2] and we are very happy with it. The best feature for us is the ease of customization.

Our challenge right now with the docs is to get a fantastic code snippet runner there. But that's beyond the scope of your regular documentation management tool, I suppose. VuePress will make it easy for us to integrate our solution.

[1] https://vuepress.vuejs.org/

[2] https://handsontable.com/docs/

Material Mkdocs

https://squidfunk.github.io/mkdocs-material/getting-started/

I like Hugo. You can chose any of the existing themes or create your own. For deployment, I wrote a simple Go server that checks a (public) GitHub repo for changes every 15 minutes and pulls + regenerates the content if necessary.

You can find it here: https://docs.pirsch.io

Antora, which uses Asciidoctor (rather than Markdown).

The obvious example is the Antora and Asciidoctor documentation:

https://docs.antora.org/antora/2.3/

https://docs.asciidoctor.org/asciidoc/latest/

We use Redoc.ly (https://www.redoc.ly) which has both a self-hosted and a managed version. I like that it integrates with GitHub, generates API Reference docs based on OpenAPI specs. It also has a "developer portal" for user guides, generated from markdown. All-in-all makes it easy to publish great-looking docs.

Preview: https://www.pinecone.io/docs/

I am "eating my own dog food" in the sense that I am currently using two projects that I developed specifically for that:

- HastyScribe[1] -- an opinionated markdown compiler that supports advanced features for technical writing like macros, fields and transclusion. - HastySite[2] -- a highly customizable static site generator based on HastyScribe and min[3], another project of mine (and a pretty deep rabbit hole to go into, if you like unusual programming languages)

Examples can be found in the docs listed for most of my with my projects, here:

https://h3rald.com/projects

The only thing missing from those is search, but I could plug in LiteStore[4] and be done with it. OK, I think that's enough self-promotion for one comment, but you did ask...

[1] https://h3rald.com/hastyscribe/

[2] https://h3rald.com/hastysite/

[3] https://h3rald.com/min/

[4] https://h3rald.com/litestore/

If you're looking for a SaaS solution, I can really recommend Archbee[0]. We've moved to it from ReadMe[1] recently, due to constraints in ReadMe's product and the challenges scaling it commercially in our model.

[0]: https://www.archbee.io/ [1]: https://readme.com/

Is there anything that supports languages other than English - specifically Indian languages. I am writing documentation (book) to be distributed online. I presently use mdbook but markdown does not support anything other than English.

https://www.mkdocs.org/. Probably not the latest or greatest, but it produces nice looking documentation from markdown. Serves my purposes well.

Markdown, Gatsby. Source is in GitHub, GHA builds the HTML output, then schleps it over to an S3 bucket.

I inherited this setup. Works great from my end, but we've got an engineering team that set it up and owns the plumbing of everything. That's key, because many orgs have a "we set it up, now it runs forever and you deal with it" mentality. And Gatsby has a super steep learning curve. And I'm not a designer.

Previously used Jekyll and still use it (minimally) for my blog. Jekyll is okay but once you get past a couple hundred pages, performance gets exponentially worse. Had a site with a few thousand pages, and builds would take an hour or more. And that org had the aforementioned problem. A team designed it, then got laid off, and I'm trying to read a dummies book to figure out what size hammer to hit the thing with.

I've been in this for 25 years, so I've used about everything else. Flare, DITA, FrameMaker, RoboHelp, PageMaker. No typewriters, thankfully.

We use [TypeDoc](https://typedoc.org/) to generate documentation from all of our TypeScript. It combines type definitions with surrounding comment blocks for easily navigable, clean documentation.

For non-TypeScript codebases, we use [Docusaurus](https://docusaurus.io/).

I believe there are also plugins which can make TypeDoc output compatible with Docusaurus.

None of our docs are public at the moment, but a good example of documentation generated by TypeDoc would be Amazon's `aws-sdk`: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index...

I’m using clowncar:

https://github.com/secretGeek/clowncar

…to turn markdown files into my “today I learned” site, here:

https://til.secretgeek.net/

A small Perl script <https://github.com/jmarshall/manconvert> that grinds a subset of man page nroff syntax directly into HTML. (That subset being “the constructs that are used in the man pages that it's used on”.)

Some of the styling could be improved (those section headings for one!), but IMHO it produces better results than other more general-purpose manpage to HTML converters: see e.g. <https://www.htslib.org/doc/samtools.html>.

I am frequently working on ways to document inline with the code using comments and then extract those comments during the build process to keep documentation up to date automatically. The comments are formatted as mark down so that they may be converted from code comments to stand alone mark down documents.

I have also noticed that in VS Code a comment immediately preceding a type or interface declaration written in mark down format becomes formatted markdown in the tooltip where that type is used.

I have a custom setup. I don't use a generator. I don't like my JS files with all these doc-comments.

The downside: quite a lot of work to create something from scratch.

The upside: I have created a playground-type API, where all options, methods & events can be tried out directly from the docs. They interact with the data grid.

https://www.datagridxl.com/api/options

As others in this thread have mentioned, Docusaurus is really good. It was very easy to add search with Algolia and meta tags for SEO as well.

A markdown generator embeds markdown from a Github repo into the marketing site. This way the marketing site is kept private while anyone can easily contribute to docs.

Docs are kept in separate folders for each release.

https://github.com/multiprocessio/datastation-documentation

I've not used it yet - but planning to give Nextra (https://nextra.vercel.app/) a go next time around.

The 'docs' theme is intended as a quick way to produce a documentation website based on Next, which you can obviously customise further with your own components if needed.

I used Help and Manual to document my software: https://www.helpandmanual.com/

It can generate HTML, CHM, PDF etc, all from a single source.

It is one of my favourite software tools (I am a customer and have no financial interest in it).

Markdown in Git, Gitlab or GitHub. KISS.

We [1] moved from mkdocs to docusaurus v2 and couldnt be happier. Very active project with a great community, and enough flexibility and config overrides when we need it.

[1] https://docs.flagsmith.com/

As I read through these comments (and discover some interesting tools!) I want to give a word of caution for anyone using this thread to make a tooling choice. The "best" documentation system for you is heavily dependent on your product [1], your contributors [2], and your ability to maintain/customize the underlying tooling. Just because you're seeing Tool X 10 times in this comment doesn't necessarily mean it's best for you!

[1] E.g. documenting an API is very different from documenting a GUI product

[2] E.g. on https://web.dev we had a large pool of authors. They were all fairly technical but even so we often ran into questions about build errors, etc.

We use asciidoctor + jekyll at $CURJOB. It seems to work great, can be hosted for free or low cost. Lots of templating wins.

I do wish it supported running code snippets, but I think that can be done with some scripts and including things. (On the list, not done yet.)

Using https://docusaurus.io/ for my side project codeamigo. It’s been great, although arguably I need to add more to the docs :)

For my project I use eleventy with markdown and commit to github which then deploys on netlify.

To make it very easy to navigate the documentation it's integrated with docsearch(algolia).

All of this is free for open source projects.

I use GitBook for https://docs.uxwizz.com/, but I want to move away from them, mostly because of their poor export features.

I want to pay for the services to be able to export PDF, but their "starting" plan is for $6.40/mo/user AND you are forced to start with at least 5 users. So I would have to pay $384 per year just to be able to export PDF for a single documentation with a single user.

Anyone know of a good hosted documentation that allows you to password protect the docs for a startup? (We don’t want public documentation and want to control access per user)

Asciidoc and Antora. We document a product that has a bunch of micro services and each micro service is in a separate git repository. We store our documentation alongside the related code in git, so it is spread out across several git repositories. Antora makes it simple to pull asciidoc files from multiple git repositories and compile it all into one static site. It also has good search functionality and support for versioning using either git branches or tags.

We're using readme.com for https://docs.numary.com/

Pretty satisfied with the productivity gain and the API docs generation from our OpenAPI file.

I just learned that their API would allow us to programmatically update the guide section as well, so we'll probably move the guides to a public github as well for contributions.

We use Vuepress for Typesense’s docs: https://typesense.org/docs/

I like the fact you can plug any vue components into the markdown. Haven’t started using that feature extensively yet, but the fact that it’s available is reassuring that I can customize things well if needed.

We recently switched from a custom markdown setup to Archbee (https://archbee.io) for our user and developer documentation. Our team loves it!

Here is our Archbee-hosted site: https://docs.invoiced.com/

In case you're using Google docs/drive for docs at the moment, I've built https://neat.wiki for precisely this purpose. If it's documentation for code there are better options though.

mdBook (or Gitbook) is also an option. A bit more general than just for docs, though they advertise it as a first class use case.

https://github.com/rust-lang/mdBook

Recently found "Just The Docs" https://pmarsceill.github.io/just-the-docs

It even incorporates search with every build.

We are using Dash ReadMe (https://dash.readme.com/login) - Easy to configure - Beautiful UX/UI - Good documentation

TL;DR: Favorite stack is Notion -> notion-markdown-cms -> VuePress -> netlify

So I've gone through a bit of journey doing docs for a product company. I feel that for a product company it's really important to own your documentation and the publishing workflow as it's a key part of your product.

GitBooks was my first stab. I liked git and markdown, however I disliked all the places where "proprietary" formatting/features crept in and once it got more closed/commercial wrt. publishing/theming pipeline we went out.

We then adopted docusaurus v1 for our product documentation. It's a great tool, but never really built custom components for it because we're not a react shop. We did integrate some nice tools to work with our markdown tool (e.g. markdown-lint, custom code snippet injectors etc). One downside of docusaurus is how much friction there is to create a new page. You have to create a markdown file, insert frontmatter, add it to sidebars.json, reload the dev server, then insert your content.

When docusaurus announced v2, we considered adopting it. Instead, we started looking into VuePress vNext. What I love about it is that its configuration is TypeScript (vs. JSON). This allows us to generate things like navbars, sidebars from code instead of manually wrangling JSON. It uses Vite for bundling and the local editing experience is therefore much faster.

As you write more and more docs, markdown editing experience becomes important. VSCode + the right plugins can get you far, but we found they all did not feel "fluent" to the point where our team _loves_ writing documentation. People often complained that our company wiki (Notion) feels much nicer, so we built a tool that allows us to use Notion as a "CMS" for our documentation: https://github.com/meshcloud/notion-markdown-cms It's really handy because that way we get perks like organizing content with databases, link pages using @mention syntax, drag & drop for screenshots etc. Publishing on netlify rounds it off.

MS Word converted with some tools to html, chm, pdf.

Stoplight.io it has support for git, CI integration

I've found https://js.wiki to be pretty good

Not sure if you can self host but I had a good experience using gitbook.com on my latest project hotstoks.com

Docusaurus. It is so easy. I only wish I could figure out how to integrate xterm.js into it.

Background: I've been a technical writer for 9 years. 6 at Google, 3 as the only writer at an IoT startup.

I helped Corrily with their docs [1] in August. They were interested in ReadMe.io. I wasn't keen on it because I had worked with Retool on their docs (hosted in ReadMe) a few years back and had found ReadMe lacking. But I was pleasantly surprised by how much it has progressed since then! If you're looking for a documentation product that is very easy to update and mostly just works, then it's worth checking out. The pricing structure gets steep very quickly though.

On https://web.dev I was introduced to Eleventy. Eleventy [2] is now my go to. The documentation for Eleventy itself is very strangely organized and needs a refactor. But I have found that there is always a way to accomplish whatever I need, and usually elegantly. Eleventy requires a lot of customization and probably wouldn't be a great fit for a huge contributor group with varying technical skill. If you're working solo or with a small team of technical people and need to do some deep customization it can be great.

Another project worth checking out is Docsy [3]. This is a Jekyll template specifically created for technical documentation.

Back at the IoT startup I had to set up the whole documentation system / tooling myself. I used Sphinx [4] and deployed to Heroku. Haven't used Sphinx since then but I remember being satisfied with it back then. reStructuredText, the flavor (?) of Markdown Sphinx uses, has some very nice features. I remember they had a very intuitive way to create tables. CSV format, I think... Again I was mostly updating the docs solo so "ease of contributing" wasn't a deciding factor (although when I left they might have struggled to update the docs, so maybe ease of contributing should always be a key factor).

I'll strike while the iron is hot here and mention that I'll probably be back on market in March - April and love to set up documentation systems (as well as write docs of course) if your company needs help with that. Poke around on my website (link in HN bio) to find my contact.

Edit: I left another comment in this thread cautioning to be careful when choosing a doc tool: https://news.ycombinator.com/item?id=29266957

[1] https://docs.corrily.com

[2] https://11ty.dev

[3] https://docsy.dev

[4] https://www.sphinx-doc.org/en/master/

Mkdocs.

Stoplight.io

hugo + netlify

Curious about why html/css is the default option here, its seems like something that is easier to save offline would dominate.