Ask HN: What are you using for public documentation these days?
110 comments
We are using Docusaurus (https://docusaurus.io/ ).
- it is easy to configure/customise
- looks really great out of the box
- solid documentation
- fast
Docusaurus is great! We migrated from Sphinx to Docusaurus[1] recently, the navigation is much better than before.
One thing that bothers us: we have not figure a way to name the anchor that both work in Github (`<span id='aws-s3'/>`) and Docusaurus (`{#aws-s3}`), for example [2]. Any ideas?
[1] https://juicefs.com/docs/community/introduction [2] https://github.com/juicedata/juicefs/blob/main/docs/en/how_t...
One thing that bothers us: we have not figure a way to name the anchor that both work in Github (`<span id='aws-s3'/>`) and Docusaurus (`{#aws-s3}`), for example [2]. Any ideas?
[1] https://juicefs.com/docs/community/introduction [2] https://github.com/juicedata/juicefs/blob/main/docs/en/how_t...
Not a great solution, but you could create the links github style, then write a remark/rehype plugin that transforms them to Docusaurus style at build time. I would probably just live with it though.
Haven't tried this but will it work on both GitHub and Docusaurus if the section "S3" is renamed as "Amazon S3" and then removing the "{#aws-s3}" part?
Yes, we can use `#amazon-s3` as the anchor, then the name could be long, for example, `#digitalocean-spaces-object-storage`), and it will not work in Chinese.
Your suggestion is better than current one, we will use that, thanks!
Your suggestion is better than current one, we will use that, thanks!
What was your motivation(s) for migrating away from Sphinx?
I'm also using Docusaurus for Fugu (https://docs.fugu.lol).
One thing that bothers me is that they offer a free Algolia integration for open-source projects, but they declined my application despite being open source.
So, search not working for now, need to have another look at that :-)
Edit: I just got an email from Algolia DocSearch saying that my documentation qualifies after all :-) If someone from that team read my comment and send the email, thanks! If not, it's a big coincidence, also good!
One thing that bothers me is that they offer a free Algolia integration for open-source projects, but they declined my application despite being open source.
So, search not working for now, need to have another look at that :-)
Edit: I just got an email from Algolia DocSearch saying that my documentation qualifies after all :-) If someone from that team read my comment and send the email, thanks! If not, it's a big coincidence, also good!
We tried to use Typesense for the search bar. We could not wrap up the PR due to bandwidth issues but it should be a great alternative for Algolia. Link: https://github.com/typesense/typesense-docsearch-scraper
Yes, that looks like a good solution! Thanks!
It doesn't support search unless you rely on (pay for) Algolia? Wow, instant pass from me.
You can add your own search plugin or use another provider like Typesense. They just offer an optional free Algolia service for open-source projects on top. You can read more here: https://docusaurus.io/docs/search
Ah phew, thanks. The site made it sound like they only supported Algolia.
> live documentation: https://docs.tooljet.io
The two separate hamburger menus were hard to parse at first on mobile. Do your social media links really deserve higher placement than the navigation?
The two separate hamburger menus were hard to parse at first on mobile. Do your social media links really deserve higher placement than the navigation?
Oh huh, I completely missed the second hamburger button and was perplexed as to why their documentation only had three links to other sites.
You are right, placing the navigation on the sidebar is more useful than the links to GitHub and Slack.
Update to a more recent version, they re-worked the nav to be one menu on mobile.
Your comment was super helpful. I just tried upgrading to 2.0.0-beta.9. The menu now looks great on mobile. The upgrade is causing some other issues, will fix those and deploy the docs. Thanks!
That was a very low-hanging fruit. Could fix and deploy it in a few minutes. There are few other improvements too related to navigation in the latest Docusaurus. Deployed here: https://docs.tooljet.com
Much better, thanks!
We also use Docusaurus. It has good defaults. If you are familiar with react, mdx (markdown + jsx) allows you to easily create and embed interactive react components.
It's technically still in beta with frequent updates, and the occasional breaking change.
For our site (https://deephaven.io/core/docs/), what I liked was the ease of adding your own plugins. We made a plugin that extracts all our code examples, and automatically tests them against new versions to notify us if any examples break or become stale.
It's technically still in beta with frequent updates, and the occasional breaking change.
For our site (https://deephaven.io/core/docs/), what I liked was the ease of adding your own plugins. We made a plugin that extracts all our code examples, and automatically tests them against new versions to notify us if any examples break or become stale.
+1 for Docusaurus. We're using it at Warrant (https://docs.warrant.dev/). In addition to what folks have already mentioned, it has good blogging support as well (markdown, post tags, SEO/social tags etc). Makes it much easier to manage both docs + blog from the same system.
Sort of curious, is there key differences between Docusauras and Hugo that would make it worth switching??
Aspect ratio of screenshots looks wrong when the docs are browsed from mobile phones. Is this a docusaurus issue or perhaps specific to your docs?
I think it is because we have explicitly set the height of the images (https://github.com/ToolJet/ToolJet/blob/develop/docs/docs/in...). Will fix it.
Your docs even support dark mode! Did that come out of the box or did you add that?
It comes out of the box. We are now trying to figure out how to switch screenshots based on the light/dark mode. The screenshots taken from light mode of ToolJet looks odd in Docusaurus' dark mode.
You could build your own react image wrapper then use that component in the mdx and pass in two images, then display the appropriate one based on the current theme provider. Docusaurus makes using inline react components easy.
You could also write your own remark plugin, that does it for you, and would have the benefit of having more control over what happens on the github side if it was still standard markdown.
You could also write your own remark plugin, that does it for you, and would have the benefit of having more control over what happens on the github side if it was still standard markdown.
Thanks, I will try creating a custom react component for handling the modes.
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 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
Another +1 from me for mkdocs and mkdocs-material (and I'm also a supporter of squidfunk). I use it for lab exercises[1] as part of my online courses (deployed onto Netlify). It just works and looks good.
[1] https://moretestable.com
[1] https://moretestable.com
+1 for Material MkDocs. It’s beautiful and functional by default so I can just focus on documenting.
Another happy user of mkdocs, also really like gitbook. If I had to choose something for people who didn't like git/plaintext and wanted richer embeds, I think I'd suggest Notion.
Oh wow this looks great! Simple conversion of markdown into an opinionated simple to use really nice looking doc site.!
Cheers for this :)
Cheers for this :)
+1000 for the "Material for MkDocs" project by squidfunk - we (Ritza.co) do documentation for various companies and we've strongly encouraged them to all switch to this since we found it. Fast, beautiful, simple.
The free version is really nice but also very happy to pay for the 'insiders' version via GitHub donations.
The free version is really nice but also very happy to pay for the 'insiders' version via GitHub donations.
Thanks for your continued support!
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...
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...
The examples look really elegant and polished. I could definitely see myself using something like this. It's times like these I wish HN had a save comment button.
Also it's pretty funny that a documentation service has incomplete documentation. https://documentation.page/documentation#how-it-works
Also it's pretty funny that a documentation service has incomplete documentation. https://documentation.page/documentation#how-it-works
If you click on the timestamp for the comment, you'll be presented with an option to "favorite" the comment.
Thanks! It's unfinished and on-hold for 3rd parties so it doesn't have all docs :)
I might retake it at some point next year to officially finish/launch it, like the code is basically mostly there.
I might retake it at some point next year to officially finish/launch it, like the code is basically mostly there.
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.
I also use sphinx and https://readthedocs.org/. lots of sphinx repos are open source so you can use them for inspiration... https://www.sphinx-doc.org/en/master/examples.html
I use this combination too, and I love it. Sphinx has great hackability and support, while github pages is free and very reliable. Here is a script that I use to publish to github pages, assuming the sphinx config is under "docs":
sphinx-build docs docs/html
git branch -D gh-pages || true
git checkout -B gh-pages-stage
touch docs/html/.nojekyll
git add --force docs/html
git commit -m "Docs"
git push --force origin $(git subtree split --prefix docs/html --branch gh-pages):refs/heads/gh-pages
git checkout -I have grown to absolutely love Sphinx. The plugins are wonderful, including Sphinx gallery, jupyter integration, and Sphinx-needs for requirements management.
I think it grows on you. There's a way to work with it and if you settle on that, it makes it easier than fighting against the prevailing tide. I find I spend a lot of time looking up opaque build errors but that is partly because the contributing authors aren't all that familiar with it, so their markdown is less than 'pure'
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.
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/
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/
I can vouch for VuePress as well. It's fairly straightforward to set up, and extremely easy to deploy. I've used it to not only write the docs for my 6502 assembler, MOS[1], but I took advantage of the fact that VuePress could generate a very simple front page as well.
[1] https://mos.datatra.sh
[1] https://mos.datatra.sh
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
You can find it here: https://docs.pirsch.io
I like Hugo as well, I'm using https://getdoks.org/
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/
The obvious example is the Antora and Asciidoctor documentation:
https://docs.antora.org/antora/2.3/
https://docs.asciidoctor.org/asciidoc/latest/
Really really love Antora. I've been pushing hard for it for internal docs -- one very nice attribute is that it can collate docs from multiple Git repos. This way, you can have documentation close to the code, like I want as a developer, while having a single "documentation site" like most management and non-technical users want.
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/
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/
- 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/
Can you link me or explain some more what you mean by macros, fields, and transclusions? Your project makes it easy to document these aspects of a programming language? Or these are features of your documentation system itself?
They are features of the documentation system itself, here's a simple example of macros:
https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm#Mac...
Basically it's like defining simple functions with parameters.
And here is a section about transclusion, which is a fancy tech writing word to say "include text from another file":
https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm#Tra...
https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm#Mac...
Basically it's like defining simple functions with parameters.
And here is a section about transclusion, which is a fancy tech writing word to say "include text from another file":
https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm#Tra...
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/
[0]: https://www.archbee.io/ [1]: https://readme.com/
What ReadMe constraints did you run into? I don't work for them, I'm just a technical writer who has to use it from time to time and wants to be aware of footguns.
The big challenges were things that were inherent to how usage scales in their platform.
As one example, they see a 'project' as one single set of cohesive documentation and they've built a UX/UI to facilitate that. This is perfectly fair but it means you need multiple projects for multiple documentation projects. In simple terms, everything in a project is intended to be 'one thing'.
Again, this might be fine but projects are so distinct and separated that it makes them really hard to maintain at scale (lots of repetition, no setting or customization sharing) and frankly, if you need the full customisation options you need to $400 a month for _each_ project.
This is a pretty unique to our model, so it's not really a criticism of readme, but it's the reason we've left. Archbee has some (not all) of the same limitations, but they don't charge us $400 a month for each project!
As one example, they see a 'project' as one single set of cohesive documentation and they've built a UX/UI to facilitate that. This is perfectly fair but it means you need multiple projects for multiple documentation projects. In simple terms, everything in a project is intended to be 'one thing'.
Again, this might be fine but projects are so distinct and separated that it makes them really hard to maintain at scale (lots of repetition, no setting or customization sharing) and frankly, if you need the full customisation options you need to $400 a month for _each_ project.
This is a pretty unique to our model, so it's not really a criticism of readme, but it's the reason we've left. Archbee has some (not all) of the same limitations, but they don't charge us $400 a month for each project!
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.
What do you mean by Markdown not supporting other languages? I don't see how it wouldn't support other languages.
Although we're using Asciidoctor (syntax / markup language) with Antora (tooling) ourselves, including with a Chinese translation. It's similar to the Fedora documentation:
https://docs.fedoraproject.org/ur_PK/docs/ (Urdu? Most translations are very incomplete; it's just volunteers.)
Although we're using Asciidoctor (syntax / markup language) with Antora (tooling) ourselves, including with a Chinese translation. It's similar to the Fedora documentation:
https://docs.fedoraproject.org/ur_PK/docs/ (Urdu? Most translations are very incomplete; it's just volunteers.)
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.
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...
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/
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>.
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 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.
Are you talking about Typescript here? If so, could you give an example of how to make this happen? This sounds incredibly useful.
I think you and austincheney might be looking for [TypeDoc](https://typedoc.org/). See my comment here: https://news.ycombinator.com/item?id=29265856
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
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
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.
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).
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.
This is my preferred option as well. Both GitLab and GitHub turn your markdown (and some other formats) files into static pages. They both have web-based editing support, so it is not necessary for a user to know anything about git to contribute. Both can automatically generate a table of contents for a page. And it gives you better versioning than any wiki system.
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/
[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.
[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.
Agreed. I'm looking for documentation software that supports a WYSIWYG or otherwise visual editor. This is because the contributors to our documentation are not very technical.
If your contributors aren't technical then things that require Markdown, Git, or a build process are rejected pretty much immediately.
Currently I'm looking at Mediawiki or WordPress, but I'd love some other suggestions for non-technical contributors.
If your contributors aren't technical then things that require Markdown, Git, or a build process are rejected pretty much immediately.
Currently I'm looking at Mediawiki or WordPress, but I'd love some other suggestions for non-technical contributors.
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.)
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.
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.
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.
Nevermind, checking their pricing https://www.gitbook.com/pricing it looks like the export feature only starts at the "Business" plan, that is $2880 to be able to export PDF, a complete joke. What's worse is that when I first started using them, they had the export to PDF feature and they removed it.
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)
You can use whatever documentation software you want, and let the web server handle access control:
https://docs.nginx.com/nginx/admin-guide/security-controls/c...
You can Google 'nginx reverse proxy authentication' to find guides.
https://docs.nginx.com/nginx/admin-guide/security-controls/c...
You can Google 'nginx reverse proxy authentication' to find guides.
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.
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.
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/
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.
Very similar, but free: https://spaceli.io/
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
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.
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.
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.
Thanks for the context. Which docs system one chooses is really dependent on that person's specific goals / product so it's helpful to see your detailed thinking here.
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/
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/
I did some freelance technical writing a while back and the customer was using readme.io. It has its quirks but at the end of the day I ended up really liking it and will likely use it again for such projects.
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.
Thanks!