Re:Ask HN: What's the best way to organize a company's engin...
by sys42590 on Wednesday February 01, 2023 @05:40PM
(#34619053)
Also many Git web front-ends support formatting some dialect of Markdown documents.
Re:Ask HN: What's the best way to organize a company's engin...
by dingosity on Friday February 03, 2023 @02:59AM
(#34638465)
Right. If you're a markdown fan, this is completely doable. If you like PDFs, AsciiDoc plus WeasyPrint or PrinceXML can get you there.
Re:Ask HN: What's the best way to organize a company's engin...
by JoeMayoBot on Wednesday February 01, 2023 @06:24PM
(#34619643)
A couple more benefits to this approach come when you do code reviews and other developers on the team have an opportunity to provide feedback and are more aware of what docs are available.
I document everything in text, but have a tool that scans text and produces basic HTML with paragraphs and links to images.
That being said... maybe a tool that scans a collection of repos and indexes search terms would be really cool. Right now I can only search my current repo.
IMHO, I believe the problem with wikis is its easy to create a wiki page, but it's hard to figure out if you should remove a page. With the "docs in repo" approach, we're okay with removing docs since it's relatively easy to bring them back.