5 ms·

We rolled our own documentation site

61 points by nerdypepper 9mo ago

WillAdams 9mo ago
For folks not familiar with this project: >Tangled is a decentralized Git hosting and collaboration platform. it is _not_ about Literate Programming (which is what I was expecting). A previous active discussion of this project: https://news.ycombinator.com/item?id=45543899 https://news.ycombinator.com/item?id=45543899
- elviejo 9mo ago
  Thank you I was also expecting Literate Programming.
sgtwompwomp 9mo ago
Mintlify is really good. If you're a serious developer tool not sure why you wouldn't use it. For example I went into your docs and I don't see AI chat so I can ask quick, natural language questions. No MCP I can install so Cursor can query. Prob no llms.txt. No quick Copy to Markdown. This stuff is table stakes, if you don't have it and a competitor does, I'm not even considering you guys It's just a worse developer experience. Fine if you aren't a serious business, but yeah I wouldn't play down the value of Mintlify or similar products. It's seriously good and it's why huge companies use it
- 4k0hz 9mo ago
  >I don't see AI chat so I can ask quick, natural language questions. No MCP I can install so Cursor can query. Prob no llms.txt. No quick Copy to Markdown. It's not the site's job to add those features though. If you want that experience there are ways to get it without adding bloat to every page on the web. Scraping a static site and answering questions/summarizing is a solved problem.
  - bognition 9mo ago
    It is the sites job to make documentation available to the users, no? It’s so odd for a tech focused crowed to be so opposed to newer technology. Users are getting used to natural language search, not having it will be perceived as friction. Users are increasingly turning to agentic coding tools, those tools do best when documentation is available via an MCP server. Not having one will make it harder for people to use your product.
    - 4k0hz 9mo ago
      I'm not opposed to the idea of natural language search, my point is the tools should be on the user side. Right now, I can ask questions about plain text pages that haven't been updated in 30 years directly in Firefox with no effort from the site operator. If an agent needs to have direct access to documentation, it's trivial for it to download pages autonomously (or even set up its own MCP server). There's literally no reason to demand that millions of sites independently add features that browsers and agents already have better and more uniform versions of.
  - add-sub-mul-div 9mo ago
    Is it surprising that an AI fanatic wants/needs to be handheld?
  - sgtwompwomp 9mo ago
    It's not a business's job to make their documentation accessible to their potential and current customers? I would ask if you've started a real business but it's clear you haven't. It is 100% on a developer tool startup to provide documentation that is easily accessible. If they don't, customers will struggle to get value. If you think this isn't true, then you are ignoring the gigantic market of companies purchasing documentation products (look at Mintlify's customer base for reference) There is no way I'm asking my customers to scrape my docs and build their own MCP server and AI assistant just to access it easily.
    - phyrog 9mo ago
      Not everything is a business, you know? As far as I know tangled is not one.
gkoberger 9mo ago
Congrats on the launch! I run a documentation product, ReadMe. There's a lot of reasons to roll your own, but I'd recommend you also look into a third-party tool like us. One of the biggest reasons to use a product is that the building v1 is easy, but keeping it up to date over time is a lot tougher... you're stuck remembering how to deploy, figuring out a workflow, dealing with multiple versions, etc. You also just don't get a ton of really great features for your developers... fast typeahead search, AI tools (which your developers increasingly really want), navigation, accessibility and more. ReadMe also lets your developers play around with you API locally and get copy-and-paste code snippets. (If you're deciding between your own and ReadMe, email me! greg@readme.io; would love to talk)
- cmoski 9mo ago
  All for the low, low price of $350 US per month!
  - gkoberger 9mo ago
    There's also a free version, and a $79/mo tier. We're also free for open source projects on our higher tiers. If it's not for you, that's okay! But an increasing number of documentation teams are cross-functional (marketing, sales, engineering, product), and not everyone is comfortable editing content directly in Git and dealing with a release. Docs are the heart and soul of most devtools, so I think it makes sense a lot of companies want a good product.
- pluralmonad 9mo ago
  I didn't find any indication on readme.io. Is it open source?
gingersnap 9mo ago
Talking about search on a static docs site, has anyone tried a static pre-generated search like https://lunrjs.com/ https://lunrjs.com/ ?
- jorams 9mo ago
  Basically every Elixir package's docs include search based on Lunr, as it's included by default by ExDoc[1]. It's quite good. [1]: https://hexdocs.pm/ex_doc/ https://hexdocs.pm/ex_doc/
- nicbou 9mo ago
  I use Lunr on allaboutberlin.com. It's simple and effective, but searching the whole content would have required loading more files than I was comfortable with. Therefore it only searches titles and descriptions. There are probably workarounds, but it's the only limitation I can think of. Otherwise Lunr just works.
- butz 9mo ago
  I think https://develop.kde.org/docs/ https://develop.kde.org/docs/ is using lunrjs for search, but downloading and parsing almost 2MB file of search data creates some hiccups on website during load.
- fanf2 9mo ago
  I use https://pagefind.app/ https://pagefind.app/ for search on my website. It’s really easy to add to a static site.
- victorbjorklund 9mo ago
  I been using this project (seems to be abandoned now but still works) https://stork-search.net/ https://stork-search.net/ Works great.
- phcreery 9mo ago
  vitepress seems to use https://github.com/lucaong/minisearch/ https://github.com/lucaong/minisearch/ and the vitepress docs I have built and used are good.
- 9mo ago
butz 9mo ago
This is great, no javascript. And while I am not a big fan of google search, alternative to open up all docs as single page and use Ctrl+F is neat.
dont__panic 9mo ago
I love the linux philosophy at work here. Pandoc is an incredible tool that every documentarian knows. Markdown is a great tool that covers 80%+ of docs requirements (admonitions and tabs are not well-defined in vanilla markdown, for instance, but you don't strictly _need_ those). I've worked on docs at quite a few companies at this point. Almost every company I've ever seen has built a Rube Goldberg machine and totally overengineered their docs for reasons I simply can't understand. It's funniest when the overengineering doesn't even solve problems better than the vanilla solutions out there like AsciiDoctor and Sphinx. So many useless checks. So much unmaintainable javascript and styling. So many botched search and AI chat implementations. And don't even get me started on Vale, which generally just annoys the hell out of contributors instead of helping them. Great work on the site, Tangled. Your docs site contains useful instructions and a sidebar that clearly communicates an organization structure. It doesn't peg my CPU or RAM. It's amazing how that makes your site better than 90% of docs sites out there. One tip: could you add a favicon? Bonus points if it's slightly distinct from your main site's favicon so I can distinguish docs tabs at a glance.
tomovo 9mo ago
Regarding the "searchability" point: I tried using the Google search field on the left to search for "openbao", which is listed right below as one of the topics. Got 0 results. Second time I tried, I got a reCaptcha from Google itself: a first in years. That's not very reassuring.
bryanhogan 9mo ago
I do have to say that all of the doc tools they mention in the beginning are worse than Astro Starlight[1] and Vitepress[2]. Can highly recommend Astro Starlight for documentation sites, used it for multiple projects myself. [1]: https://starlight.astro.build/ https://starlight.astro.build/ [2]: https://vitepress.dev/ https://vitepress.dev/
- magnio 9mo ago
  Can vouch for Starlight and Astro in general. Don't be fooled by the fact that they are npm packages: Astro is geared for content-heavy websites and produces zero-JS bundles by default (i.e., if you just use markdowns without any script tags or JS frontend libraries, then there will be no JS in the final output at all).
rvdginste 9mo ago
I recently created a static site with technical documentation using Antora. Antora uses asciidoc source that it pulls from git repositories. It has a lunr extension for search. It took some time to get familiar with the setup, but I find it very nice to work with. I use it for the documentation of a set of code libraries, and it is a really good fit for that.
effnorwood 9mo ago
https://aicoding.leaflet.pub/3mcbiyal7jc2y https://aicoding.leaflet.pub/3mcbiyal7jc2y
rileymichael 9mo ago
> MkDocs: Works great with JS disabled, however the table of contents needs to be maintained via mkdocs.yml, which can be quite tedious. note that the mkdocs-material folks are now working on https://zensical.org/ https://zensical.org/ which is in rust and _much_ faster. it solves this specific requirement by autogenerating the navigation based on file structure. it's still early / under active development, but i recently rebuilt our techdocs on top of it. a simple github workflow to aggregate from our two monorepos + some bash-fu to merge them together and voila! no config file headaches

61 points by nerdypepper 9mo ago

For folks not familiar with this project: >Tangled is a decentralized Git hosting and collaboration platform. it is _not_ about Literate Programming (which is what I was expecting). A previous active discussion of this project: https://news.ycombinator.com/item?id=45543899 https://news.ycombinator.com/item?id=45543899

elviejo 9mo ago
Thank you I was also expecting Literate Programming.

sgtwompwomp 9mo ago

Mintlify is really good. If you're a serious developer tool not sure why you wouldn't use it. For example I went into your docs and I don't see AI chat so I can ask quick, natural language questions. No MCP I can install so Cursor can query. Prob no llms.txt. No quick Copy to Markdown. This stuff is table stakes, if you don't have it and a competitor does, I'm not even considering you guys It's just a worse developer experience. Fine if you aren't a serious business, but yeah I wouldn't play down the value of Mintlify or similar products. It's seriously good and it's why huge companies use it

4k0hz 9mo ago
>I don't see AI chat so I can ask quick, natural language questions. No MCP I can install so Cursor can query. Prob no llms.txt. No quick Copy to Markdown. It's not the site's job to add those features though. If you want that experience there are ways to get it without adding bloat to every page on the web. Scraping a static site and answering questions/summarizing is a solved problem.
- bognition 9mo ago
  It is the sites job to make documentation available to the users, no? It’s so odd for a tech focused crowed to be so opposed to newer technology. Users are getting used to natural language search, not having it will be perceived as friction. Users are increasingly turning to agentic coding tools, those tools do best when documentation is available via an MCP server. Not having one will make it harder for people to use your product.
  - 4k0hz 9mo ago
    I'm not opposed to the idea of natural language search, my point is the tools should be on the user side. Right now, I can ask questions about plain text pages that haven't been updated in 30 years directly in Firefox with no effort from the site operator. If an agent needs to have direct access to documentation, it's trivial for it to download pages autonomously (or even set up its own MCP server). There's literally no reason to demand that millions of sites independently add features that browsers and agents already have better and more uniform versions of.
- add-sub-mul-div 9mo ago
  Is it surprising that an AI fanatic wants/needs to be handheld?
- sgtwompwomp 9mo ago
  It's not a business's job to make their documentation accessible to their potential and current customers? I would ask if you've started a real business but it's clear you haven't. It is 100% on a developer tool startup to provide documentation that is easily accessible. If they don't, customers will struggle to get value. If you think this isn't true, then you are ignoring the gigantic market of companies purchasing documentation products (look at Mintlify's customer base for reference) There is no way I'm asking my customers to scrape my docs and build their own MCP server and AI assistant just to access it easily.
  - phyrog 9mo ago
    Not everything is a business, you know? As far as I know tangled is not one.

gkoberger 9mo ago

Congrats on the launch! I run a documentation product, ReadMe. There's a lot of reasons to roll your own, but I'd recommend you also look into a third-party tool like us. One of the biggest reasons to use a product is that the building v1 is easy, but keeping it up to date over time is a lot tougher... you're stuck remembering how to deploy, figuring out a workflow, dealing with multiple versions, etc. You also just don't get a ton of really great features for your developers... fast typeahead search, AI tools (which your developers increasingly really want), navigation, accessibility and more. ReadMe also lets your developers play around with you API locally and get copy-and-paste code snippets. (If you're deciding between your own and ReadMe, email me! greg@readme.io; would love to talk)

cmoski 9mo ago
All for the low, low price of $350 US per month!
- gkoberger 9mo ago
  There's also a free version, and a $79/mo tier. We're also free for open source projects on our higher tiers. If it's not for you, that's okay! But an increasing number of documentation teams are cross-functional (marketing, sales, engineering, product), and not everyone is comfortable editing content directly in Git and dealing with a release. Docs are the heart and soul of most devtools, so I think it makes sense a lot of companies want a good product.
pluralmonad 9mo ago
I didn't find any indication on readme.io. Is it open source?

gingersnap 9mo ago

Talking about search on a static docs site, has anyone tried a static pre-generated search like https://lunrjs.com/ https://lunrjs.com/ ?

jorams 9mo ago
Basically every Elixir package's docs include search based on Lunr, as it's included by default by ExDoc[1]. It's quite good. [1]: https://hexdocs.pm/ex_doc/ https://hexdocs.pm/ex_doc/
nicbou 9mo ago
I use Lunr on allaboutberlin.com. It's simple and effective, but searching the whole content would have required loading more files than I was comfortable with. Therefore it only searches titles and descriptions. There are probably workarounds, but it's the only limitation I can think of. Otherwise Lunr just works.
butz 9mo ago
I think https://develop.kde.org/docs/ https://develop.kde.org/docs/ is using lunrjs for search, but downloading and parsing almost 2MB file of search data creates some hiccups on website during load.
fanf2 9mo ago
I use https://pagefind.app/ https://pagefind.app/ for search on my website. It’s really easy to add to a static site.
victorbjorklund 9mo ago
I been using this project (seems to be abandoned now but still works) https://stork-search.net/ https://stork-search.net/ Works great.
phcreery 9mo ago
vitepress seems to use https://github.com/lucaong/minisearch/ https://github.com/lucaong/minisearch/ and the vitepress docs I have built and used are good.
9mo ago

butz 9mo ago

This is great, no javascript. And while I am not a big fan of google search, alternative to open up all docs as single page and use Ctrl+F is neat.

dont__panic 9mo ago

I love the linux philosophy at work here. Pandoc is an incredible tool that every documentarian knows. Markdown is a great tool that covers 80%+ of docs requirements (admonitions and tabs are not well-defined in vanilla markdown, for instance, but you don't strictly _need_ those). I've worked on docs at quite a few companies at this point. Almost every company I've ever seen has built a Rube Goldberg machine and totally overengineered their docs for reasons I simply can't understand. It's funniest when the overengineering doesn't even solve problems better than the vanilla solutions out there like AsciiDoctor and Sphinx. So many useless checks. So much unmaintainable javascript and styling. So many botched search and AI chat implementations. And don't even get me started on Vale, which generally just annoys the hell out of contributors instead of helping them. Great work on the site, Tangled. Your docs site contains useful instructions and a sidebar that clearly communicates an organization structure. It doesn't peg my CPU or RAM. It's amazing how that makes your site better than 90% of docs sites out there. One tip: could you add a favicon? Bonus points if it's slightly distinct from your main site's favicon so I can distinguish docs tabs at a glance.

tomovo 9mo ago

Regarding the "searchability" point: I tried using the Google search field on the left to search for "openbao", which is listed right below as one of the topics. Got 0 results. Second time I tried, I got a reCaptcha from Google itself: a first in years. That's not very reassuring.

bryanhogan 9mo ago

I do have to say that all of the doc tools they mention in the beginning are worse than Astro Starlight[1] and Vitepress[2]. Can highly recommend Astro Starlight for documentation sites, used it for multiple projects myself. [1]: https://starlight.astro.build/ https://starlight.astro.build/ [2]: https://vitepress.dev/ https://vitepress.dev/

magnio 9mo ago
Can vouch for Starlight and Astro in general. Don't be fooled by the fact that they are npm packages: Astro is geared for content-heavy websites and produces zero-JS bundles by default (i.e., if you just use markdowns without any script tags or JS frontend libraries, then there will be no JS in the final output at all).

rvdginste 9mo ago

I recently created a static site with technical documentation using Antora. Antora uses asciidoc source that it pulls from git repositories. It has a lunr extension for search. It took some time to get familiar with the setup, but I find it very nice to work with. I use it for the documentation of a set of code libraries, and it is a really good fit for that.

effnorwood 9mo ago

https://aicoding.leaflet.pub/3mcbiyal7jc2y https://aicoding.leaflet.pub/3mcbiyal7jc2y

rileymichael 9mo ago

> MkDocs: Works great with JS disabled, however the table of contents needs to be maintained via mkdocs.yml, which can be quite tedious. note that the mkdocs-material folks are now working on https://zensical.org/ https://zensical.org/ which is in rust and _much_ faster. it solves this specific requirement by autogenerating the navigation based on file structure. it's still early / under active development, but i recently rebuilt our techdocs on top of it. a simple github workflow to aggregate from our two monorepos + some bash-fu to merge them together and voila! no config file headaches