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

11–20 of 111 posts

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

#11

Post by franciscop »

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

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

#13

Post by eysi »

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.

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

#15

Post by navaneethpk »

We are using Docusaurus (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 and here is the live documentation: https://docs.tooljet.com/

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

#17

Post by pcthrowaway »

austincheney wrote: post #2

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…

Are you talking about Typescript here? If so, could you give an example of how to make this happen? This sounds incredibly useful.

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

#18

Post by newaccount74 »

navaneethpk wrote: post #15

We are using Docusaurus ( 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 and here is the live documentation: https://docs.tooljet.com/

Your docs even support dark mode! Did that come out of the box or did you add that?

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

#19

Post by djrockstar1 »

franciscop wrote: post #11

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

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

#20

Post by navaneethpk »

newaccount74 wrote: post #18
navaneethpk wrote: post #15

We are using Docusaurus ( 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 and here is the live documentation: https://docs.tooljet.com/

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