3 ms·

I wouldn't even bother with the static site generator. While I like the idea of STGs, in my opinion, they all suck. And now there has to be someone to maintai

I wouldn't even bother with the static site generator. While I like the idea of STGs, in my opinion, they all suck. And now there has to be someone to maintain how those pages are rendered and know how whatever thing like Jekyll works. Just let developers either read the markdown files as-is or set their IDE to render markdown previews by default. I prefer the latter because I don't have to wait for someone who's on vacation half the time to render the latest docs. When it comes to API documentation, everything should just be inline comments in the doc format of choice for the team. Don't bother rendering this out, because every flipping tool ever invented for converting inline documentation into HTML fails on something simple. Developers can read the inline docs as-is and/or rely on their IDE to provide them hints from those docs. If you have to deploy your documentation, that's how you know you might as well give up. It's one thing to deploy documentation for 3rd parties, but for documentation being used internally there's few good reasons to turn the documentation into its own website. That's extra work that I've never seen increase productivity or developer happiness. Don't put documentation behind one or two guys with special permissions to press a deploy button. If you do, the documentation will always be out of date as soon as it's rendered. Remove as many reasons that devs won't write documentation as you possibly can.

rcarr 4y ago
I do think just using the folder of markdown folders is far preferable to browsing on the web wherever possible but there's definite use cases where it's unavoidable. I do think this is a very strong case for using Obsidian however, because you literally don't have to mess about with maintaining any kind of SSG, you just put `publish: true` in the metadata of whatever note you want publishing and then just click the Publish button and it's there on the website.
vlmutolo 4y ago
Rust's rustdoc tool does an excellent job converting comments to HTML. The documentation for almost every public Rust library is automatically rendered and hosted on docs.rs and it's incredible to have that consistency. Just check out this Regex type and the awesome documentation for every method, all taken from inline comments: https://docs.rs/regex/latest/regex/struct.Regex.html https://docs.rs/regex/latest/regex/struct.Regex.html
- diordiderot 4y ago
  I wish more languages had this!

rcarr 4y ago

I do think just using the folder of markdown folders is far preferable to browsing on the web wherever possible but there's definite use cases where it's unavoidable. I do think this is a very strong case for using Obsidian however, because you literally don't have to mess about with maintaining any kind of SSG, you just put `publish: true` in the metadata of whatever note you want publishing and then just click the Publish button and it's there on the website.

vlmutolo 4y ago

Rust's rustdoc tool does an excellent job converting comments to HTML. The documentation for almost every public Rust library is automatically rendered and hosted on docs.rs and it's incredible to have that consistency. Just check out this Regex type and the awesome documentation for every method, all taken from inline comments: https://docs.rs/regex/latest/regex/struct.Regex.html https://docs.rs/regex/latest/regex/struct.Regex.html

diordiderot 4y ago
I wish more languages had this!