Ask HN: What are your favorite tools for generating simple documentation?
I need to write some pretty simple documentation, just a general overview of a code base's structure, installation requirements, and usage. I'm leaning toward just putting everything in a README markdown file, but I might want to expand it a bit more eventually, and it would also be nice to have a static HTML file I could hand over to a team which may not have a markdown reader.
I've been looking at different documentation generators, and getting a little overwhelmed by all the options. Maybe I just need a markdown-to-html converter? What is your favorite way to write simple documentation?
6 comments
[ 2.9 ms ] story [ 22.6 ms ] threadhttps://github.com/hofstadter-io/cuetorials.com is one of the sites I maintain using Hugo. It started as the Docsy theme, but needed to be changed due to limitations
I picked sphinx at old job because we had very good infra for it. Even though I found it slow (due to it being python based and my company’s idiosyncrasies)
For my current job, I picked docfx because other people used them and have set up infra for them. I preferred vite press because editing experience was way better with its HMR. However, I couldn’t change the company infra, so docfx it is.
Using vitepress (for writing)and docfx (for publishing) didn’t work due to their subtle differences.
My recommendation would be using vitepress, as it makes editing easier and you really want this part to be as much frictionless as possible.
And do not go with sphinx as it requires restructuredText. Rst is good, but it introduces a learning curve.