Live data from Hacker News

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

news.ycombinator.com

71–80 of 111 posts

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

#71
I 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

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/

[2] https://h3rald.com/hastysite/

[3] https://h3rald.com/min/

[4] https://h3rald.com/litestore/

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

#72
Background: 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 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

[1] https://docs.corrily.com

[2] https://11ty.dev

[3] https://docsy.dev

[4] https://www.sphinx-doc.org/en/master/

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

#73
We 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 Preview: https://mockoon.com/docs/latest/

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

#74
TL;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 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.

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

#75

Earlier quoted context omitted.

You are right, placing the navigation on the sidebar is more useful than the links to GitHub and Slack.

Update to a more recent version, they re-worked the nav to be one menu on mobile.

That was a very low-hanging fruit. Could fix and deploy it in a few minutes. There are few other improvements too related to navigation in the latest Docusaurus. Deployed here: https://docs.tooljet.com

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

#76
post #71

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

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

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

#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

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

#78

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/

Docusaurus is great! We migrated from Sphinx to Docusaurus[1] recently, the navigation is much better than before. One thing that bothers us: we have not figure a way to name the anchor that both work in Github (` `) 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...

What was your motivation(s) for migrating away from Sphinx?
Post reply on HN