3 ms·

I find that the best way to build docs is to use some sort of a static html generator and host the html yourself, which is not at all hard to do. There are free

I find that the best way to build docs is to use some sort of a static html generator and host the html yourself, which is not at all hard to do. There are free and open source themes available to host your own docs in various site generators. My personal favorite is hugo. Previously I have built a documentation for a large project [0] using hugo and it gave us 100% control over how we design or host it. Outsourcing a doc to a SaaS seems like something I would never do if I cared about the product/software. [0] - https://docs.dgraph.io https://docs.dgraph.io

pc86 8y ago
> Outsourcing a doc to a SaaS seems like something I would never do if I cared about the product/software. I'm inclined to agree, however I could see the argument for it if you are printing money (so even something expensive like readme.io [no affiliation] is inconsequential) and you've got something in place to keep everything up to date, and the docs are well integrated to your new engineering hire onboarding.
zeddabaeen 8y ago
@stockkid hey! This works great for small dev teams, but once you get technical writers around and the team gets bigger, static documentation just doesn't cut it and is unable to scale with the demand. Hugo is amazing, but this is the same thing with buying your own hardware and racks, or hosting with Amazon. It's all about the managed service and peace of mind! Thanks, Z
- stockkid 8y ago
  > once you get technical writers around and the team gets bigger, static documentation just doesn't cut it and is unable to scale I feel that this is not convincing because docs for large software projects are also built using static site generators and git (e.g. docker). In my case, we had many devs including a full-time technical writer contributing to the doc using Hugo and GitHub pull request and had no problems. I am curious what you think the bottlenecks of static documentation are.

pc86 8y ago

> Outsourcing a doc to a SaaS seems like something I would never do if I cared about the product/software. I'm inclined to agree, however I could see the argument for it if you are printing money (so even something expensive like readme.io [no affiliation] is inconsequential) and you've got something in place to keep everything up to date, and the docs are well integrated to your new engineering hire onboarding.

zeddabaeen 8y ago

@stockkid hey! This works great for small dev teams, but once you get technical writers around and the team gets bigger, static documentation just doesn't cut it and is unable to scale with the demand. Hugo is amazing, but this is the same thing with buying your own hardware and racks, or hosting with Amazon. It's all about the managed service and peace of mind! Thanks, Z

stockkid 8y ago
> once you get technical writers around and the team gets bigger, static documentation just doesn't cut it and is unable to scale I feel that this is not convincing because docs for large software projects are also built using static site generators and git (e.g. docker). In my case, we had many devs including a full-time technical writer contributing to the doc using Hugo and GitHub pull request and had no problems. I am curious what you think the bottlenecks of static documentation are.