[cedws]

Docs should be as close to source code as possible, ideally in the same repo so they can be updated and reviewed in the same PR as the source changes themselves. Markdown works fine.

For docs that don’t relate to source, just have a repo for general docs. Not only is Confluence absolute crap, tech docs in it rot because it’s a separate system developers don’t want to use. Similar story for MediaWiki.

[Terr_]

I would also strongly favor documentation diagrams which can be rebuilt from "code", such as PlantUML, Mermaid, and the venerable GraphViz formats.

[brewmarche]

I agree but aren’t there docs that might be needed by non-technical people as well. The general doc repo might contain “bureaucratic” information (what I mean is who owns the application, what is the security concept, what other apps does it communicate with and who are their owners, how does it get audited, etc.).

Of course we can set up an export to a static website from the repo, but how would a non-technical person edit it, say if the owner or audit process changes?

[spondylosaurus]

Certain static sites can hook up into a WYSIWYG CMS backend, although I'm not sure how nice they play with version control.

[kody]

I would kill for code-adjacent docs right now.

We're a documentation-heavy org and having to open Confluence, find the right root page, drill down to where I need to be, and deal with ~1s page loads drives me nuts.

[crayola]

Fully agree -- documentation as markdown committed alongside the code (and processes to ensure that it is kept up-to-date, discoverable and browsable) is the best way to avoid docs going stale or abandonned.

[hiAndrewQuinn]

You can go all the way and make a Hugo website out of those Markdown docs pretty easily too. If anyone wants help doing this, feel free to drop me a line!