atw: Re: Replacing Word (Long...)
- From: Ken Fredric <KenFredric@xxxxxxxxxxxxx>
- To: "'austechwriter@xxxxxxxxxxxxx'" <austechwriter@xxxxxxxxxxxxx>
- Date: Thu, 21 Apr 2011 11:47:19 +1000
And of course, for those of us who have the luxury of moving away from Word for
at least some of our work, DITA has already provided another set of tools for
doing this.
Cheers,
Ken
________________________________
From: austechwriter-bounce@xxxxxxxxxxxxx
[mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of Christine Kent
Sent: Thursday, 21 April 2011 11:29 AM
To: austechwriter@xxxxxxxxxxxxx
Subject: atw: Re: Replacing Word (Long...)
I tend to agree, Bob. Resistance is futile. I recently did some training on
Office 2010 where the environment was using Citrix. Quite simply, it was a dog
to make compatible, so the environment will eventually upgrade to SharePoint.
It all comes down to compatibility. As MS does this better and better, there
will be less and less room for variety. In our business our only option is to
become very good at Word, with a very minor niche for a few people in
Framemaker. How many of us can afford to become gurus in tools used by 2 ½
people?
Christine
From: austechwriter-bounce@xxxxxxxxxxxxx
[mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of Bob Trussler
Sent: Thursday, 21 April 2011 10:45 AM
To: austechwriter@xxxxxxxxxxxxx
Subject: atw: Re: Replacing Word (Long...)
Like it or not, everyone uses MS Word.
Very few places have a specialised wordprocessor for publishing, and they
usually have MS Word for technical staff and SMEs to write the drafts. Most
web sites have their content written in MS Word.
A republishing tool for the web or online help or anything else that does not
take MS Word docs as input is just not used.
Get used to it.
Bob T
On 21 April 2011 08:36, Christine Kent
<cmkentau@xxxxxxxxx<mailto:cmkentau@xxxxxxxxx>> wrote:
James, you are ignoring the organisational reasons why a business goes with
a single product. Only large and dedicated tech writing departments can
really benefit from having a dedicated software, and for them it is valid to
argue for such. However, in most organisations I have worked with, the
materials I produce have to move backwards and forwards between myself and
the corporate wide users. Messy and totally horrible though it often is,
particularly for compiling large documents, most organisations will make the
call to have only one product.
To be fair to MS, the changes made in recent years have led me to believe
that MS is not remotely interested in developing Word as a tech writing
tool, nor do they ever promote it as such. They do not even have a "book"
template, meaning they are not promoting Word even for the production of
books, which it does perfectly well.
All the significant changes of 2007/10 have been to make it more user
friendly for the average user. Features that are important to high level
niche users, such as master documents, cross references, mail merge and the
like have not been touched since at least 2003 and probably go back very
much further. This neglect implies quite strongly that MS is not interested
in them. We can only speculate as to whether they will eventually improve
them in one big hit, or perhaps come out with a niche product, or whether we
are too small a component of their market for them to care less what we
think.
Christine
-----Original Message-----
From:
austechwriter-bounce@xxxxxxxxxxxxx<mailto:austechwriter-bounce@xxxxxxxxxxxxx>
[mailto:austechwriter-bounce@xxxxxxxxxxxxx<mailto:austechwriter-bounce@xxxxxxxxxxxxx>]
On Behalf Of James Hunt
Sent: Wednesday, 20 April 2011 11:52 PM
To: austechwriter@xxxxxxxxxxxxx<mailto:austechwriter@xxxxxxxxxxxxx>
Subject: atw: Replacing Word (Long...)
The proposition that Microsoft Word is not a good tool for technical and
corporate writing is widely accepted, and the shortcomings of the product
have been described in detail in many places. According to a British
technical writer in a recent blog comment -
"Once again, someone has pointed out the fact that MS Word is not really
suitable as an enterprise technical writing tool unless it is heavily
customized. Have programmers create special document-creation interfaces,
create locked purpose-built ribbons, use SEQ fields instead of native
numbering... Here we go again. I've seen and heard this exact same thing too
many times... People keep saying Word will work for tech writing IF you
change this and customize that and renoberate the other thing. Face it, this
is like saying that a car will work as a helicopter if you totally rebuild
every part of it. If you have to spend that much time, effort, and money
making it work the way you want, it would be worth your while if only in
avoided irritation to go get something that already works the way you need
it to work. And if you have to try to change your corporate culture to make
the tool usable, it's NOT worth the effort. You are supposed to use tools,
not the other way around."
Outbursts like this, and there have been many of them over the years, never
seem to change anything. We keep on using a product that has serious
problems, and reduces our working efficiency quite noticeably.
I do not propose to add another lament to this pile. Instead, I propose to
point out that a superior alternative exists, that the alternative is
stable, is bug-free for all practical purposes, and has been tested by
millions of writers over several decades. Furthermore, it is free, and in
use involves far less effort than does Word. I will describe in a little
detail how this tool, in conjunction with a freeware version control system
and a few other tools, can be used to perform documentation tasks more
efficiently than we could with Word.
Technical writers are usually in control of a complete end-to-end process:
we research our material, write it, rewrite it, and eventually check the
formatting and deliver documents to end users.
Are there any other writers like us? The answer is yes: engineers,
physicists, other physical scientists, mathematicians, and even computer
scientists, who write journal articles, books, and reports for publication
in scientific journals or by scientific book publishers or by their own
employers. These writers are found largely, but not exclusively, in
universities and research institutes. There may well be a few million of
them - no-one knows for certain.
These scientific writers all use a simple markup language and typesetting
program called LaTeX, which has been around since the 1980s, and is based on
a system called TeX that was developed in the 1970s. (LaTeX is not used by
all scientists: biologists rarely use it, but it is also used by
non-scientists: I have come across theological tomes typeset in multiple
languages with LaTeX.)
Microsoft Word is a WYSIWYG system, which means that text is typeset as it
is entered: the writing and typesetting tasks are conflated in a single
window. This has the unfortunate result that the input file is continually
modified by the typesetter, and errors in the typesetting process will
instantly corrupt that input file. This is not the case with LaTeX: writers
write in text editors, not word processors, and insert formatting tags into
their text in the form of text strings after escape characters (such as
"\chapter", "\section" or "\list"). Input files are pure text files, with no
hidden formatting information. When a typeset version of a file is required,
the text file is sent to the background typesetting program, which reads the
tags in the text as commands and produces the required PDF output. (This is
not hard: usually clicking on the "Typeset" button on your text editor will
do the job.) The input files remain unchanged by this process. If the result
is unsatisfactory, will have still have your unmodified input text files for
checking.
The typesetting algorithm in LaTeX is much more sophisticated than that used
in Word, and the result is quite noticeably better: it is even better than
anything that Adobe InDesign or QuarkXPress can do. In fact, LaTeX
typesetting is of book-publication quality, and is used by many technical
publishers.
Is it possible to learn from all of those LaTeX-using writers, and build on
their experience? Yes, and I will argue that we should do exactly that.
LaTeX is not hard to learn: you can learn the basics in a day and become
quite skilled in a week. The mastery so obtained is yours for a lifetime,
because the core of LaTeX does not change. Books on LaTeX are often
dauntingly thick, because LaTeX was developed for typesetting mathematics,
and large chunks of LaTeX texts are devoted to that topic. We don't do that.
We don't need to learn about the complexities of academic referencing
either, because most software and engineering user guides do not contain
bibliographies and citations. When these items are left out of the average
LaTeX book, the remainder comprises a discussion of about fifty tags - not
many more than basic HTML. This is what is learned in a day. Going beyond
the default style options, which give very good results anyway, will take a
few more days' work. Authors of books on LaTeX are often apologetic about
the "steep learning curve" involved, but it is steep only if you need to do
some mathematical heavy lifting.
This site is a good start: http://latex.silmaril.ie/formattinginformation/
A PDF version is available at:
http://latex.silmaril.ie/formattinginformation/beginlatex-a4.pdf
For instructions on downloads, see: http://ctan.org/starter.html
For a more substantial reference, see:
http://upload.wikimedia.org/wikipedia/commons/2/2d/LaTeX.pdf
I won't duplicate the material in those sites here. The core of LaTeX is
small and easy to learn, and if you want to do something outside the scope
of the core, then you will need an add-on package designed to do that task.
There seem to be thousands of these, all designed for a particular purpose:
drawing Feynman diagrams for physicists, adding hyperlinks to the PDF
output, setting out manuscripts for science fiction and fantasy publishers,
making page margins visible, writing in all manner of alphabets, and so on
and on. You can ignore most of them.
Our basic products are books and book-like objects, ranging in length from a
few pages to several hundred pages: user guides, installation guides,
reference manuals, and so on. These were once actual printed books, but are
now mostly PDF files on a server. We also produce lots of ancillary
material, most notably on-line help systems, but also quick-reference
guides, instruction cards, training manuals, presentations, and so on. All
of these can be produced using LaTeX.
----------
Tools - summary
----------
The tools required for writing our materials comprise a text editor, a LaTeX
distribution (the basic typesetter and a collection of interesting add-on
packages), a version control system, a screen capture utility, and a
graphics editor. All of these are available as freeware.
----------
Text editors
----------
There are quite a few editors, and they are interchangeable because they all
produce only text files. Most are freeware; some are minimalist (TeXShop),
and some have more buttons and control panels than a nuclear power station
(texmaker). TeXShop, TeXworks and Kile are commonly used. Prehistoric
products like emacs are still around, and do the job quite nicely.
----------
Revision control
----------
There are a number of freeware revision control systems available.
Subversion may be the most widely used, but there are others, such as Git,
that are just as good. Revision control systems are most useful when
handling plain text files, and these are what text editors produce.
Revision control systems are useful if successive editions are required for
successive software releases, or if several writers work on a single
project.
If you are working on a software development project, the simplest approach
may be to use the system selected by the project manager.
----------
Illustrations
---------
Illustrations in various formats may be included by reference in LaTeX
documents: PNG, JPG, and PDF screenshots may all be used.
The open-source scalable vector graphics editor, Inkscape
(http://inkscape.org/), has many of the capabilities of Adobe Illustrator.
Inkscape illustrations can be included in LaTeX documents.
----------
What about XML?
----------
The major problem with XML tagging is getting the files to print. Now a
major feature of LaTeX is that the tags inserted in the text are later read
as commands by the typesetting program. This is not the case with so-called
XML formatters: some of these work by substituting LaTeX tags for XML tags,
and then processing the generated LaTeX files in the usual way, while others
have their own typesetting programs - which never seem to be anywhere near
as good as LaTeX. The former approach merely adds an extra processing step,
and the latter reinvents (part of) the wheel.
----------
How far can this model of work extend?
----------
The work model described works very well for a single writer producing all
the documents required for a project, where that writer may or may not be
using a version control system. Can the model be extended to projects with
multiple writers, or even multiple writers producing multiple documents in a
range of languages? Of course.
----------
Multiple authors writing different chapters
----------
Let us suppose that you are the lead writer on an enormous software
development project, and that you have assigned different chapters of the
various books to several other writers. The writers (and you) write in text
editors, and at regular intervals they test their work by making sure that
it can compile to PDF without errors, and then commit the text files (not
the PDF files, which are only temporary) to the version control system. You
may then extract copies of the various updated files from the version
control system, and compile the full PDF versions of the various manuals.
(This process could even be automated as part of the daily build process.)
The write-test-compile cycle is the same as the one that characterises
software development.
----------
Successive releases of a software product
----------
Let us suppose that your company has released version 1.0 of the software
and started to develop version 1.1. The files under version control are
suitably marked as "Version 1.0", and the writing process continues until
development is frozen and the final PDF documents for Version 1.1 are
produced.
----------
Managing translations
----------
If your company decided to localize the product and sell it from Iceland to
China with local-language manuals, how would you go about preparing those
manuals?
First of all, the text strings displayed on the various windows of a
software product are all stored in one file, and imported to the program
windows by reference. To produce other-language versions of the software,
new files of text strings must be prepared, and the user must be able to
select a language and store it as a preference. Thus the software developers
can produce twenty or more different language versions of the product, and
it is up to you to provide the required manuals in those twenty-odd
languages.
If you used a number of screen shots to illustrate the base-language manual,
then you will have to capture the same screen shots for all the other
language versions. A tedious business. Name the new screen shots
systematically - for example: "screenshot_01_1_de.png",
"screenshot_19_1_fi.png", ... (If you used Inkscape to prepare drawings, and
used LaTeX tags to label them, then the text in the drawings may be
translated with the text documents.)
Send copies of the base-language text files (for Version 1.0, say) to the
chosen translation house. The translators will not need to change the tags,
only the text: LaTeX tags remain in US English no matter what language is
used in the document. Eventually, you will get back sets of text files of
the translations. Edit the various "\includepicture" tags to make sure that
the screen shots all go into the right manuals.
Next, compile the PDF versions. There will be errors, no matter how many
times you tell the translators to Leave the Damn Tags Alone: correct the
errors, insert a tag specifying the language at the start of each master
document (to ensure that the correct hyphenation algorithm is used for each
language) and compile, and you will have a collection of elegantly typeset
manuals most of which you probably cannot read.
Producing the first set of translations is hugely expensive. However, when
it is time to produce the various translations of the Version 1.1 manual,
the cost can be much lower. The aim is not to translate anything that was
translated before, and translate only the changes made in the base-language
version. The changes between Versions 1.0 and 1.1 can be pin-pointed by any
version control system. The translators can find the matching lines in the
foreign-language text files, make the required changes, and save the results
as Version 1.1 for each of the various languages. Again, the files come back
to you for checking and compilation.
Projects of this scope and complexity are not common, but the proposed set
of tools could certainly handle them.
----------
What about document reviews?
----------
There are two ways to allow reviewers to comment on drafts: allow them to
have access to the text files in the version control system, or give them
PDF versions into which they can insert comments. The latter procedure is
preferable.
Adobe Reader alone cannot be used to insert comments in PDF documents
generated by LaTeX. Adobe Acrobat can do this, but it costs money, and I
prefer an all-freeware solution.
Foxit Reader for Windows is free, and can be used to annotate PDF documents
generated by LaTeX. You will need to download the software for your
reviewers from http://www.foxitsoftware.com/pdf/reader/reader4.php.
Under OS X, the supplied PDF viewer Preview contains annotation tools.
Comments by reviewers can be incorporated - or not - into text files as part
of the revision process.
----------
Is there a PowerPoint replacement?
----------
Yes: there are LaTeX document classes that generate PDF files whose text can
be revealed line-by-line.
----------
What about those embarrassing hidden-text problems in Word?
----------
Lines and blocks of text can be hidden in LaTeX in two ways: put a "%" sign
at the beginning of every line that you want left out of the generated PDF
document, or just move the text after the "\end{document}" tag. Nothing
after that tag appears in the PDF document.
----------
Conclusions
----------
LaTeX is a stable program, proven in use by many writers in scientific and
technical fields. It is easy to learn, and the core of the program has not
changed for many years. In conjunction with other freeware tools such as
version control systems and PDF document annotation software, it can be used
confidently in documentation projects of considerable complexity.
So -
Why not make our lives easier?
----------
----------
**************************************************
To view the austechwriter archives, go to
www.freelists.org/archives/austechwriter<//www.freelists.org/archives/austechwriter>
To unsubscribe, send a message to
austechwriter-request@xxxxxxxxxxxxx<mailto:austechwriter-request@xxxxxxxxxxxxx>
with
"unsubscribe" in the Subject field (without quotes).
To manage your subscription (e.g., set and unset DIGEST and VACATION modes)
go to
www.freelists.org/list/austechwriter<//www.freelists.org/list/austechwriter>
To contact the list administrator, send a message to
austechwriter-admins@xxxxxxxxxxxxx<mailto:austechwriter-admins@xxxxxxxxxxxxx>
**************************************************
**************************************************
To view the austechwriter archives, go to
www.freelists.org/archives/austechwriter<//www.freelists.org/archives/austechwriter>
To unsubscribe, send a message to
austechwriter-request@xxxxxxxxxxxxx<mailto:austechwriter-request@xxxxxxxxxxxxx>
with "unsubscribe" in the Subject field (without quotes).
To manage your subscription (e.g., set and unset DIGEST and VACATION modes) go
to
www.freelists.org/list/austechwriter<//www.freelists.org/list/austechwriter>
To contact the list administrator, send a message to
austechwriter-admins@xxxxxxxxxxxxx<mailto:austechwriter-admins@xxxxxxxxxxxxx>
**************************************************
--
Bob Trussler
Phone 0418 661 462
-------------------------------Safe Stamp-----------------------------------
Your Anti-virus Service scanned this email. It is safe from known viruses.
For more information regarding this service, please contact your service
provider.
Other related posts:
