What do *you* do for documentation?
Thomas N. Mackey
from VT52's, uucp was the only way to move files from one machine to
another, and newgroups like net.sources existed, I guess I'm an old
fogey. Back in those days, nearly a decade ago, certain activities were
easier. Perhaps the one aspect that bugs me the most is that in spite
of all the improvements, document preparation by a group of people is
more difficult than ever.
Let me explain. Nine years ago I was working in a group of five other
developers and we were writing a document describing the system we were
working on. We were using nroff, had agreed on the '-me' set of macros,
and had the whole document divided up into sections in a directory
structure that mirrored the structure of the document. We had a Makefile
that would assemble the whole thing or pieces of it, as required. All
the files were stored under RCS control, so we could all work on all the
pieces as necessary. I admit that it had few graphics, and those we did
with some crude ascii art. The document wasn't very pretty, in comparison
to what we can do today, but it had several advantages. Pieces of it
could be worked on from home, using a PC with a terminal emulator. We
all let nroff do the work of formatting the document, so we usually left
existing lines of text alone when we added to or modified the document.
Thus running rcsdiff would show (usually) just the changes someone might
be interested in, rather than hundreds of lines of changes just because
someone added a word somewhere.
My point is that applications such as Interleaf, Frame, MS-Word and the
like, while producing nice looking docs, do so while sacrificing the
ability to edit the docs away from the workstation. Also sacrificed is
the ability for a large team to work on the docs, good version control
of sub-sections using standard UNIX version control tools, and the
ability to easily see what changes have been made over time.
I am curious as to how others have solved these problems while using the
powerful publishing systems available today. What do you do to maintain
version control, how do you deal with the fact that most doc preparation
systems produce binary files which do not lend themselves well to finding
differences? What do you do when documents might have to be worked on by
several groups which may not have the same tools available? What if the
document has to be worked on from an old tyme ascii terminal? How do you
handle dependancies a la make(1)?
Please help this one old fogey drag hisself kicking and screaming into the
21st Century!
--
Character is like a fence: it can't be strengthened with whitewash.
Thomas N. Mackey (Tom) to...@halcyon.com
Matthew Harrison
writes:
> My point is that applications such as Interleaf, Frame, MS-Word and the
> like, while producing nice looking docs, do so while sacrificing the
> ability to edit the docs away from the workstation. Also sacrificed is
> the ability for a large team to work on the docs, good version control
> of sub-sections using standard UNIX version control tools, and the
> ability to easily see what changes have been made over time.
>
> I am curious as to how others have solved these problems while using the
> powerful publishing systems available today. What do you do to maintain
> version control, how do you deal with the fact that most doc preparation
> systems produce binary files which do not lend themselves well to finding
> differences? What do you do when documents might have to be worked on by
> several groups which may not have the same tools available? What if the
> document has to be worked on from an old tyme ascii terminal? How do you
> handle dependancies a la make(1)?
Delta encoding relies on the structure of ascii text (CR separated lines) to
efficiently encode differences, using ed commands. For WP documents it would need to
know their structure to be able to efficiently work out what's really changed, and
have a standard way of encoding it. Binary has no assumed structure. If the WP makers
also provided a diff with their software, which RCS could use instead of diff with
their document formats, then we'd be cooking with gas. I suppose that's what an OO
operating system like Taligent or Cairo is meant to be all about.
Unfortunately, until OpenDoc, OLE 2.0 or whatever, are standard, the plug and play
nature of UNIX which is lost in a GUI environment of megalithic apps will be a dream
to some and a memory to others.
> Please help this one old fogey drag hisself kicking and screaming into the
> 21st Century!
With a UNIX background, why kick and scream, you've got a great head start. I like
GUIs but don't let the Mr Point-and-Clicks put you down.
_____
\ -,`\ Matthew Harrison
\ `__/ BioRad Microscience UK
__ \ \ __ Ph (+44)(0)442 232 552
/ \ / \__\ \ Fax (+44)(0)442 234 434
/ /\ \/ /\ ___ \ Email mat...@colussus.demon.co.uk
/_/ \__/ \_\ \_\
Matthew Harrison
> In article: <2qm1so$5...@nwfocus.wa.com> to...@halcyon.halcyon.com (Thomas N.
> Mackey)
> writes:
[ deleted reply to some article in a completely different thread about
documentation, which I posted using an alpha test MS-windows-based news reader.
The auto word wrap worked fine but was set too wide, I think. ]
Oops. Random thread poster.
--