[p4] Documentation file formats (Or: How do you manage docs across bra nches ?)

Oren Shemesh orens at p-cube.com
Tue Jun 15 00:18:36 PDT 2004


Hi all,

I have a question about common practices regarding software documentation
files:

For a software product which is managed in more than one branch (e.g. /dev,
/v1 and /v2), which has documentation files (containing the spec,
high-level-design, etc), how do you manage the branch/merge of documentation
files ?

Common wisdom suggests that we should handle documentation like any other
source file, so it should be stored with the source files and
branched/merged with them, BUT - in P-Cube we use Micro$oft Word .doc files,
and they are not easily mergable.

Do other companies use mergable formats (HTML, LaTech(?), .rtf, .txt) ?
People here insist that it is not practical to move away from Microsoft
Office. What tools are used to create documentation files (with text,
tables, graphics) which are mergable ?

If you work with Office, but save in some text-based format (Such as HTML or
RTF), is it safe to say that making a small change in the document will make
only a small change in the output file ? If not, then simply switching to a
text-based format does not help much...

I would appreciate any feedback/insight on this matter.

Thanks, Oren.





More information about the perforce-user mailing list