News for hackers. Stuff that matters.
Re:Making world-class docs takes effort by fragmede on Monday September 06, 2021 @06:49PM (#28438984)
"product-level user-facing documentation written by non-engineers" is at one end of the spectrum, and clearly wants to use a different tool (eg Adobe InDesign) with code comments written by engineers at the other. Problem is, how do you navigate everything else that's in-between, while minimizing strife from one side making demands (some reasonable, others not) to the other.

Where do your business critical spreadsheets go?

Re:Making world-class docs takes effort by simonw on Monday September 06, 2021 @07:19PM (#28439177)
I think most documentation at a company can and should live outside of version control repositories - the key thing is to have editing tools that non-engineers can use and to ensure that the resulting material can be effectively published, searched and made visible to the people who need access to it.

The exception is engineering documentation: API docs should absolutely be version-controlled in the same place as the code they are describing.

I built an internal search engine for a past employer that covered 11 different sources of documentation - Confluence, Google Docs, GitHub Markdown, Salesforce Support and more - and it really helped solve some of the discoverability problems we were having.