mark VS go-atlassian

Readme.md should be the very first source of documentation. From there we may have a nested “docs” directory all written in markdown and then as part of CI we sync that all into confluence on merges to dev using https://github.com/kovetskiy/mark

We use Mark[1] to automatically create Confluence pages from Markdown documents in our git repos. So we can have a review process for documentation changes, the documentation of the code can be in the repo with the code, and yet it can still be accessed without having to give permissions to view the code repo! Helpful with a proprietary monorepo.

[1] https://github.com/kovetskiy/mark

I used https://github.com/kovetskiy/mark at my last job where I had to use Confluence. It wasn't perfect and some touchup was generally needed after a sync but it definitely helped me stay sane.

At the UAT/Production stage, the documentation is pushed to the Wiki using the extension of choice (most documentation parsers support the major wiki providers, like for Confluence there's Mark for Markdown, Official AsciiDoctor Exporter, and RST Exporter), or parsed into a DocBook/eBook/PDF for publishing.

See a full documentation at docs.go-atlassian.io.