Ask HN: What are you using for public documentation these days? On a new side project I'm working on I need to have a fair amount of documentation for usage, implementation, options, etc. In the past I've used https://docsify.js.org hosted on Vercel, but I was curious if there is anything else out there people like. Looking for free or paid options. So long has I can host on a subdomain I'm indifferent. Thanks! |
[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.
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.
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.)
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 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.
https://docs.nginx.com/nginx/admin-guide/security-controls/c...
You can Google 'nginx reverse proxy authentication' to find guides.
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.
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.
Here is our Archbee-hosted site: https://docs.invoiced.com/
It even incorporates search with every build.
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.
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
[2] https://11ty.dev
- it is easy to configure/customise
- looks really great out of the box
- solid documentation
- fast
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 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!
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?
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.
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
Cheers for this :)
The free version is really nice but also very happy to pay for the 'insiders' version via GitHub donations.
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...
Also it's pretty funny that a documentation service has incomplete documentation. https://documentation.page/documentation#how-it-works
I might retake it at some point next year to officially finish/launch it, like the code is basically mostly there.
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 -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.
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.
https://squidfunk.github.io/mkdocs-material/getting-started/
You can find it here: https://docs.pirsch.io
The obvious example is the Antora and Asciidoctor documentation:
Preview: https://www.pinecone.io/docs/
- 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:
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/
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...
[0]: https://www.archbee.io/ [1]: https://readme.com/
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!
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.)
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.
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...
https://github.com/secretGeek/clowncar
…to turn markdown files into my “today I learned” site, here:
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 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.
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.
Docs are kept in separate folders for each release.
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.
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).
Your suggestion is better than current one, we will use that, thanks!
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.