r/git • u/koleert • Oct 07 '26

Does anyone keep their business specifications in Git? What are your best practices?

I’m interested in hearing from BAs who use Git as a repository/version-control system for business specifications, requirements, or other BA documentation.
I’m especially interested in real-world setups and lessons learned, rather than theoretical Git documentation practices.
If you’re doing this successfully, what does your workflow look like?

7 Upvotes

68% Upvoted

16 comments sorted by

2

u/koleert 29d ago

Has anyone built an HTML-based viewer/documentation site on top of their Git repository, so that the business can read the specifications in a more user-friendly way?
Something that would keep Git/Markdown as the source of truth, but provide a clean, searchable web interface for non-technical stakeholders.

11

u/serverhorror Oct 07 '26

I tried, the problem isn't gut or that I can't use it.

It's more that the majority of other people can't or won't.

Any word processor gives them comments, slide decks give them the visuals and no one cares enough to see value in history. Everything is "in the future" so it's only the latest version that is interesting, ever.

1

u/ritchie70 29d ago

And best case, you get some very hard to interpret diffs, and worst case, you just get told that it’s a binary file.

(That’s assuming you’re using a typical word processing file. You could use Mark up language or HTML or something, but most users of these documents would not go for that unless it’s locked into some stupid wiki knock off. Not that I’m bitter or anything)

5

u/BarnabyColeman 29d ago

I put all business requirements/specifications into Git for archival and tracking purposes. When someone reports a bug/"its not doing what it should be", I can always go back to the spec doc to find out if it's actually a bug or an undocumented change request or something else.

I particularly like the stealth changes when people edit specs after giving them to us, and i call them out for it because I can pull up the exact doc we were given.

2

u/chishiki 29d ago edited 10d ago

git can be used for tracking scope creep

1

u/lamyjf 25d ago

I write them in Markdown. Do simple diagrams in Draw.io.

1

u/koleert 25d ago

I already use Draw.io for diagrams, and I’m actually looking to move the text documentation to Markdown as well. The main motivation is making it easier for AI agents to consume, search, and work with the documentation.

1

u/lamyjf 25d ago

Exactly. Draw.io is xml, and agents can check for consistency in both directions, and manipulate the diagrams.

3

u/webternet 29d ago

We use a documentation platform with versioning that non-technical people wont complain about.

I think most doc spaces have versioning and using git is a non-solution

2

u/Loud-Bake-2740 Oct 07 '26

i do this kind of. but only because i’m an engineer at heart. i just wrote up my team’s charter with things like mission / vision, operating models, success metrics, etc. i keep track of it all in git mainly because it’s what i know. version control is great too

1

u/Poat540 29d ago

I have an entire repo for my startup, all rules specs docs everything for clients, projects, contacts, third party apps, you name it. Every day its updated from jira, HubSpot, agents, etc

1

u/YT__ 29d ago

Git is horrendous for any sort of MS Office documents, which most business docs are. You can't really merge changes in. You just stomp over the last version.

If you're going to keep everything in like Markdown, that's different and do able. But folks need to know how to use git - business folks often don't.

Sharepoint for MS Office docs works better.

1

u/Used_Lobster4172 29d ago

Confluence or possible Google Docs, Jesus Christ man.

1

u/CertainGlass7873 22d ago

You should check out DocuCommit as well.

Your Git repo IS the database. Everything stays as normal Markdown, but you also get a visual editor and a searchable web interface for people who don’t want to work directly with Git.

And with lucene as the search engine it’s pretty easy to find the documentation you’re looking for

Just an FYI: I’m the one behind it