[comp.sys.mac.programmer] SUMMARY: file format for distributing technical documentation

ari@eleazar.dartmouth.edu (Ari Halberstadt) (09/08/90)

This is a summary of responses to an article I posted recently to
"comp.sys.mac.programmer" and "comp.sys.mac.apps". Many thanks to the
folks on the network who took the time to reply to my posting. There
were far too many responses for me to reply to each one individually,
but I'll summarize the basic ideas in most of the comments.

The first paragraph of my original posting was:
| 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?
Many people said things like (these are not actual quotes):
     "I'd go with MacWrite and Word" (this was the most popular response).
     "RTF: my gosh, that brain dead thing from the DOS world."
     "RTF: no no no, I can't read that..."
     "TeachText: Everybody's got it"
     "MacWrite: Almost everybody's got it."
     "Word: Many people have it, and I've seen lots of
     documentation distributed in word."
     "Postscript: That's a last resort."
     "SuperGlue: well, you have to buy it, but then you can distribute
     a free viewer application that everyone can use."
     "Batchprint: a free self contained viewer program available from
     vega.hut.fi (130.233.200.42) in /pub/mac/finnish/deskjet."

I've gone through all the mail and tallied the scores for the programs
mentioned. Included in the tally are only actual mentions of a
program. That is, if someone said "I love Microsoft Word", the
response would get a "Yes" score. If someone said "I can't read RTF"
then the response got a "No" score, and if someone said "PostScript
can be used as a last resort" it got a "Maybe" score. If the response
didn't mention a program then no score was given.

	Program			Yes/No/Maybe
	------------------------------------
	Microsoft Word 3.0	yyyyyyy
	Postscript		ym
	RTF			ynnnnn
	MacWrite < 5.0		yyyyym
	TeachText		yyyy
	DocMaker		m
	SuperGlue*		yym
	BatchPrint		yy

As you can see, Microsoft Word 3.0 is in first place, with not a
single "No" or "Maybe" vote. MacWrite (pre version 5.0) takes second
place, and TeachText comes in third. The format I was going to use,
(RTF-Rich Text Format) is obviously not a part of the Macintosh world.
Again, I am indebted to the network community for their advice, which
prevented me from distributing the documentation in a format which no
one could read. I have decided to distribute the manuals in Microsoft
Word and MacWrite formats.
-- 
-- Ari Halberstadt
ari@eleazar.dartmouth.edu

dorner@pequod.cso.uiuc.edu (Steve Dorner) (09/08/90)

In article <24096@dartvax.Dartmouth.EDU> ari@eleazar.dartmouth.edu (Ari Halberstadt) writes:
>As you can see, Microsoft Word 3.0 is in first place, with not a
>single "No" or "Maybe" vote.

If I'd have known you were taking votes, you sure would have gotten at least
one "no" vote on Microsoft Word.  Up til a month ago, I didn't have
ANYTHING that would read such a document.
--
Steve Dorner, U of Illinois Computing Services Office
Internet: s-dorner@uiuc.edu  UUCP: uunet!uiucuxc!uiuc.edu!s-dorner