Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: What are you using for public documentation these days?

news.ycombinator.com

Post reply on HN
Print view View original

91–100 of 111 posts

Re: Ask HN: What are you using for public documentation these days?

#91

Post by squidfunk »

sixhobbits wrote: post #59
evolve2k wrote: post #21

Earlier quoted context omitted.

Oh wow this looks great! Simple conversion of markdown into an opinionated simple to use really nice looking doc site.! 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.

Thanks for your continued support!

Re: Ask HN: What are you using for public documentation these days?

#92

Post by kaycebasques »

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.

Re: Ask HN: What are you using for public documentation these days?

#93

Post by ak217 »

stichers wrote: post #4

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 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 -

Re: Ask HN: What are you using for public documentation these days?

#96

Post by jonjon10002 »

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.

Re: Ask HN: What are you using for public documentation these days?

#97

Post by verdverm »

marvinblum wrote: post #77

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

Big fan of Hugo too

https://cuetorials.com

https://github.com/hofstadter-io/cuetorials.com

Re: Ask HN: What are you using for public documentation these days?

#98

Post by twalla »

tomw1808 wrote: post #6

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

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.

Re: Ask HN: What are you using for public documentation these days?

#99

Post by innocentoldguy »

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.
Post reply on HN