8 ms·
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!
- DarthNebo 5y agoRecently found "Just The Docs" https://pmarsceill.github.io/just-the-docs https://pmarsceill.github.io/just-the-docs It even incorporates search with every build.
- diveanon 5y agoCurious about why html/css is the default option here, its seems like something that is easier to save offline would dominate.
- stichers 5y agoBasic 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.
- acidburnNSA 5y agoI have grown to absolutely love Sphinx. The plugins are wonderful, including Sphinx gallery, jupyter integration, and Sphinx-needs for requirements management.
- stichers 5y agoI 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'
- byteface 5y agoI also use sphinx and https://readthedocs.org/ 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 https://www.sphinx-doc.org/en/master/examples.html
- ak217 5y agoI 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 -
- dabeeeenster 5y agoWe [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/ https://docs.flagsmith.com/
- krish888 5y agoStoplight.io
- franciscop 5y agoI have an unfinished side project called Documentation Page: https://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/ https://statux.dev/: simple single-page docs and website, menu config in https://github.com/franciscop/statux/blob/master/documentation.page.json https://github.com/franciscop/statux/blob/master/documentati.... - https://react-test.dev/ 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/documentation.page.json https://github.com/franciscop/react-test/blob/master/documen... - https://crossroad.page/ 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/documentation.page.json https://github.com/franciscop/crossroad/blob/master/document...
- djrockstar1 5y agoThe 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 https://documentation.page/documentation#how-it-works
- ryannevius 5y agoIf you click on the timestamp for the comment, you'll be presented with an option to "favorite" the comment.
- franciscop 5y agoThanks! 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.
- krish888 5y agoStoplight.io it has support for git, CI integration
- pydry 5y agohugo + netlify
- navaneethpk 5y agoWe are using Docusaurus (https://docusaurus.io/ 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 https://github.com/ToolJet/ToolJet/tree/develop/docs and here is the live documentation: https://docs.tooljet.com/ https://docs.tooljet.com/
- gompertz 5y agoSort of curious, is there key differences between Docusauras and Hugo that would make it worth switching??
- newaccount74 5y agoYour docs even support dark mode! Did that come out of the box or did you add that?
- navaneethpk 5y agoIt 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.
- dsmmcken 5y agoYou 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.
- navaneethpk 5y agoThanks, I will try creating a custom react component for handling the modes.
- fenesiistvan 5y agoMS Word converted with some tools to html, chm, pdf.
- andix 5y agoMarkdown in Git, Gitlab or GitHub. KISS.
- oftenwrong 5y agoThis 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.
- Jefro118 5y agoIn case you're using Google docs/drive for docs at the moment, I've built https://neat.wiki https://neat.wiki for precisely this purpose. If it's documentation for code there are better options though.
- grodriguez100 5y agoVery similar, but free: https://spaceli.io/ https://spaceli.io/
- samcrawford 5y agohttps://www.mkdocs.org/ https://www.mkdocs.org/. Probably not the latest or greatest, but it produces nice looking documentation from markdown. Serves my purposes well.
- warpech 5y agoWe (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/ https://vuepress.vuejs.org/ [2] https://handsontable.com/docs/ https://handsontable.com/docs/
- royjacobs 5y agoI 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 https://mos.datatra.sh
- Symbiote 5y agoAntora, which uses Asciidoctor (rather than Markdown). The obvious example is the Antora and Asciidoctor documentation: https://docs.antora.org/antora/2.3/ https://docs.antora.org/antora/2.3/ https://docs.asciidoctor.org/asciidoc/latest/ https://docs.asciidoctor.org/asciidoc/latest/
- davidwf 5y agoReally 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.
- davidandgoliath 5y agoMkdocs.
- superzamp 5y agoWe're using readme.com for https://docs.numary.com/ 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.
- parkersweb 5y agoI've not used it yet - but planning to give Nextra (https://nextra.vercel.app/ 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.
- jacobmischka 5y agomdBook (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
- Joe8Bit 5y agoIf 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/ https://www.archbee.io/ [1]: https://readme.com/ https://readme.com/
- kaycebasques 5y agoWhat 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.
- Joe8Bit 5y agoThe 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!
- robbiejs 5y agoI 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 https://www.datagridxl.com/api/options
- lizparody 5y agoWe are using Dash ReadMe (https://dash.readme.com/login https://dash.readme.com/login) - Easy to configure - Beautiful UX/UI - Good documentation
- jomar 5y agoA small Perl script <https://github.com/jmarshall/manconvert 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 https://www.htslib.org/doc/samtools.html>.
- eatonphil 5y agoA 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 https://github.com/multiprocessio/datastation-documentation
- hermitcrab 5y agoI used Help and Manual to document my software: https://www.helpandmanual.com/ 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).
- auspex 5y agoAnyone 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)
- rahimnathwani 5y agoYou can use whatever documentation software you want, and let the web server handle access control: https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/ https://docs.nginx.com/nginx/admin-guide/security-controls/c... You can Google 'nginx reverse proxy authentication' to find guides.
- gk1 5y agoWe use Redoc.ly (https://www.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/ https://www.pinecone.io/docs/
- eduardosasso 5y agoNot sure if you can self host but I had a good experience using gitbook.com on my latest project hotstoks.com
- marvinblum 5y agoI 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 https://docs.pirsch.io
- verdverm 5y agoBig fan of Hugo too https://cuetorials.com https://cuetorials.com https://github.com/hofstadter-io/cuetorials.com https://github.com/hofstadter-io/cuetorials.com
- crossworth 5y agoI like Hugo as well, I'm using https://getdoks.org/ https://getdoks.org/
- jaredtking 5y agoWe recently switched from a custom markdown setup to Archbee (https://archbee.io https://archbee.io) for our user and developer documentation. Our team loves it! Here is our Archbee-hosted site: https://docs.invoiced.com/ https://docs.invoiced.com/
- kaycebasques 5y agoAs 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 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.
- justin_oaks 5y agoAgreed. 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.
- luizfelberti 5y agoI've found https://js.wiki https://js.wiki to be pretty good
- webwanderings 5y agoDocusaurus. It is so easy. I only wish I could figure out how to integrate xterm.js into it.
- XCSme 5y agoI use GitBook for https://docs.uxwizz.com/ 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.
- XCSme 5y agoNevermind, checking their pricing https://www.gitbook.com/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.
- austincheney 5y agoI 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.
- pcthrowaway 5y agoAre you talking about Typescript here? If so, could you give an example of how to make this happen? This sounds incredibly useful.
- loh 5y agoI think you and austincheney might be looking for [TypeDoc](https://typedoc.org/ https://typedoc.org/). See my comment here: https://news.ycombinator.com/item?id=29265856 https://news.ycombinator.com/item?id=29265856
- plondon514 5y agoUsing https://docusaurus.io/ https://docusaurus.io/ for my side project codeamigo. It’s been great, although arguably I need to add more to the docs :)
- tomw1808 5y agoI'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/ https://squidfunk.github.io/mkdocs-material/ [2] https://ethereum-blockchain-developer.com https://ethereum-blockchain-developer.com
- evolve2k 5y agoOh wow this looks great! Simple conversion of markdown into an opinionated simple to use really nice looking doc site.! Cheers for this :)
- sixhobbits 5y ago+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.
- squidfunk 5y agoThanks for your continued support!
- 4kelly 5y ago+1 for Material MkDocs. It’s beautiful and functional by default so I can just focus on documenting.
- twalla 5y agoAnother 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.
- tedyoung 5y ago
- perfopt 5y agoIs 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.
- Symbiote 5y agoWhat 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/ https://docs.fedoraproject.org/ur_PK/docs/ (Urdu? Most translations are very incomplete; it's just volunteers.)
- woudsma 5y agoAs 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.
- eysi 5y agoWe 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.
- LeonB 5y agoI’m using clowncar: https://github.com/secretGeek/clowncar https://github.com/secretGeek/clowncar …to turn markdown files into my “today I learned” site, here: https://til.secretgeek.net/ https://til.secretgeek.net/
- loh 5y agoWe use [TypeDoc](https://typedoc.org/ 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/ 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.html https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index...
- mooreds 5y agoWe 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.)
- 015a 5y agoMaterial Mkdocs https://squidfunk.github.io/mkdocs-material/getting-started/ https://squidfunk.github.io/mkdocs-material/getting-started/
- h3rald 5y agoI 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 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/ https://h3rald.com/hastyscribe/ [2] https://h3rald.com/hastysite/ https://h3rald.com/hastysite/ [3] https://h3rald.com/min/ https://h3rald.com/min/ [4] https://h3rald.com/litestore/ https://h3rald.com/litestore/
- kaycebasques 5y agoCan 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?
- h3rald 5y agoThey are features of the documentation system itself, here's a simple example of macros: https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm#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#Transclusion https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm#Tra...
- kaycebasques 5y agoBackground: 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 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 https://news.ycombinator.com/item?id=29266957 [1] https://docs.corrily.com https://docs.corrily.com [2] https://11ty.dev https://11ty.dev [3] https://docsy.dev https://docsy.dev [4] https://www.sphinx-doc.org/en/master/ https://www.sphinx-doc.org/en/master/
- geocrasher 5y agoI 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.
- 255kb 5y agoWe have an handmade website using Next.js. It generate the documentation from the markdown files present in the `content` folder. It was not the easiest path, but it does the job. Code: https://github.com/mockoon/mockoon.com https://github.com/mockoon/mockoon.com Preview: https://mockoon.com/docs/latest/ https://mockoon.com/docs/latest/
- jrudolph 5y agoTL;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 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.
- kaycebasques 5y agoThanks 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.
- zabil 5y agoFor 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.
- jabo 5y agoWe use Vuepress for Typesense’s docs: https://typesense.org/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.
- jonjon10002 5y agoMarkdown, 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.
- innocentoldguy 5y agoAsciidoc 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.