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

Neal Freeman Neal.Freeman at VoltEurope.com
Tue Jun 15 01:20:42 PDT 2004

This must be an almost universal problem. Will it be solved for Microsoft
Office documents by the ability to save them in xml format? I hope so!

-----Original Message-----
From: perforce-user-admin at perforce.com
[mailto:perforce-user-admin at perforce.com]On Behalf Of Oren Shemesh
Sent: 15 June 2004 08:19
To: Perforce User Group (E-mail)
Subject: [p4] Documentation file formats (Or: How do you manage docs
across bra nches ?)

Hi all,

I have a question about common practices regarding software documentation

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.

perforce-user mailing list  -  perforce-user at perforce.com

Gatton Place, St Matthews Road, Redhill, Surrey, RH1 1TA. 
Registered in England No. 1739576. 
E-mail: enquiries at volteurope.com 	Website: www.volteurope.com 

VOLT EUROPE is a member of the IT Division of REC. 
Visit www.rec.uk.com for the latest REC & industry news. 

VOLT EUROPE is a member of ATSCo ( www.atsco.org ). 
Setting the Standard for IT Recruitment. 

This message, together with any attachments, is confidential information
intended solely for the use of the addressee(s). It must not be disclosed to
another person or used for any purpose not authorised by Volt. If you are
not the intended recipient you must not print, copy, use, disclose or
distribute any part of this message. If you receive this message in error,
please delete it and any copies and notify the sender immediately. This
email has been virus scanned before sending. Volt will not be liable for any
effect there may be on your systems or data on receipt of this email, nor
for any changes made to it after it was sent. Volt reserves the right to
monitor and/or record emails addressed to Volt and its employees and senders
of messages shall be taken to consent to this. 

Any contractual representations contained herein on behalf of Volt must not
be taken as final and are entirely subject to formal written confirmation or
contract signed by an authorised representative of Volt. Further information
on Volt's terms and conditions of business can be obtained from our website.

More information about the perforce-user mailing list