Importance of diffing and merging for design specifications documentation
The context of this question is choosing tools for writing design
specifications for software projects.
These documents will be written and maintained by architects and
developers, I'm not talking about marketing requirements. Some of them may
be shared outside the team, but only in a processed, non-editable form
(PDF).
These are architecture documents, describing the structure of code
components, implementation methods, protocols, data formats, etc. They
take the form of text with diagrams and identifier names and the
occasional code snippets, this isn't about API documentation that might be
generated from source files.
The docs will be under source control, fortunately nobody here needs to be
educated about that. It's inevitable that versioning will arise over time:
we do maintain old versions of the software. Issue tracking might not be
adhered to as strictly for documentation as for code.
How important is it to be able to easily compare and merge such documents?
We have diverging opinions in the team, ranging from "nobody ever merges
documentation and if needed Word has a merge tool" to "merging is crucial
and git merge must work".
I have a vague memory of a rule in some company (Google, perhaps, since
it's so often cited) that "if you can't merge it, it doesn't exist", but
I'm unable to find it now.
I'm looking for either well-reasoned arguments, or authoritative-looking
(and preferably motivated) citations.
No comments:
Post a Comment