Why my docs live in git

I'm increasingly convinced that the ideal tool for developers and architects to use for written documentation, and even communication, is markdown, stored in git.

What's wrong with sharepoint/confluence...?

Every documentation repository I've worked with has had the same problems:

• docs are scattered
• docs are outdated
• search is unreliable or returns many inauthorative results
• the history and context of the document is missing  

Why?

• If our docs are not tied to the thing they are describing, they become outdated
• Our code is reusable, our docs are not (reorganising is a big job, and from the moment it's done, entropy sets in again)
• We're using publishing tools as a single source of truth for our information, but it's then locked in that platform, and difficult to move elsewhere

What should we be doing?

• Writing docs in a simple format that's easy to edit, and easy to parse (by humans and machines) - markdown
• Storing docs in a git repo, which has great support for multi-user editing
• Publishing this information where it's needed, using our existing CI tools

Examples

• Architectural decision records
• Guides with Docausauras
• Presentations with Reveal-md
• Markdown with components using MDX
• Diagrams with Mermaid
• Collaborative, embeddable diagrams with Excalidraw
• Document metadata (think tags, authors, progress indicators) with Frontmatter
• This blog - written in Obsidian, stored in Github, published to Netlify with Gatsby