Product docs alongside product code

As a PM, I thought this was about documenting the details of features and their functionality. I recently joined a startup with no documentation at all, and I spent a great deal of time documenting how everything worked. Even then, I kept being surprised by new functionality.

I agree that technical docs should be the closest to the code. But one problem of that is docs is more difficult to discover. As you need to browse the repo and docs is in the middle of source code.

What I tried to do, is to use Github API to list all .md files in a repo and index them as if they were Confluence/Notion/.. docs (with tags, attributes, folders, ...). One issue, there is not a lot of granularity in the permission system of github, and the app would need to have a view right on all files of each repo, which can be an issue when you offer this app as Saas. Same this is not possible to share only one file of a repo with an external app

I've always wanted a setup like this! It is so much easier to author docs when you can tie them directly to functionality and manage through PRs.

How are you planning on managing the publishing workflow for non-devs? Marketing and docs teams tend to struggle quite a bit with git specific flows.