Xref: utzoo comp.sys.mac.programmer:17006 comp.sys.mac.apps:1261
Path: utzoo!utgpu!news-server.csri.toronto.edu!mailrus!cs.utexas.edu!swrinde!zaphod.mps.ohio-state.edu!rpi!bu.edu!dartvax!eleazar.dartmouth.edu!ari
From: ari@eleazar.dartmouth.edu (Ari Halberstadt)
Newsgroups: comp.sys.mac.programmer,comp.sys.mac.apps
Subject: What file format should technical documentation be distributed in?
Summary: Problem: incompatible word processors; request suggestions
Message-ID: <23862@dartvax.Dartmouth.EDU>
Date: 24 Aug 90 01:33:11 GMT
Sender: news@dartvax.Dartmouth.EDU
Followup-To: comp.sys.mac.programmer
Organization: Dartmouth College, Hanover, NH
Lines: 40

Dear Macintosh Users,

I am about to post a set of free XFCNs, including source code
and over 100 pages of documentation. The documentation has
been specially formatted in the style of technical documentation.
I would like to distribute the documentation so that the maximum
number of people will be able to read it, with all of its
formatting and illustrations intact. My question is, in what format
should the files be distributed?

I wrote the documentation in Microsoft Word 3.1. Unless told otherwise,
I intend to distribute the files in Microsoft Word's Rich Text Format [RTF].
Unfortunately, even when uploading into Microsoft Word 4.0, there are
some losses in the formatting commands. If the same corporation can't
maintain compatability between its products, I see little reason why
word processors from other manufacturers will be able to interpret the
files.

I have tried saving the files in MacWrite format, but this looses most
of the formatting. If I manually fix up the file, I can get some 
improvement, but this has proven too time consuming and error-prone.
Since the software is free, I will be unable to offer printed versions
of the manuals. 

Obviously, the problem of distributing documentation for the Macintosh
is very serious. There seems to be no standard which will cope with
complicated formatting information. The Macintosh is supposed to
be easy to use, yet it requires its users to worry about obscure
file formats. This situation is reminiscent of the DOS world, a world
we would like to think the Macintosh has improved uppon.

Any suggestions will be appreciated.

Sincerely,


Ari Halberstadt

ari@dartmouth.edu
--