[sofixa]

> I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL

There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc.

( Tools used are Gitlab CI, mark and Confluence, but they don't really matter, the workflow does).

[polote]

I didn't know it already existed. I'm working on something similar via a Github app which watch new commits made on master and offer to the commiter to upload its new .md files on the wiki.

As you said having the dev doc on an external tool is really a plus. You can have comments, you can add tags, easier to search, and give access to non technical people

[Cthulhu_]

Yeah, you could add a job to your CI that runs a compiler and outputs the result to a web page that can be accessed by all. I'm sure there's ways and means to have a web based editor that can commit into version control as well.

[sa46]

I really like the sound of this. That’s how Google’s internal technical docs worked. Write markdown in src repo, get nice, searchable doc site in return.

Anyone know if a tool like that already exists to turn README.md files into a website?

[sofixa]

There are a few ones, the only one that comes to mind is Docusaurus from iirc Facebook.