atw: Re: Replacing Word (Long...)
- From: Bob Trussler <bob.trussler@xxxxxxxxx>
- To: austechwriter@xxxxxxxxxxxxx
- Date: Thu, 21 Apr 2011 10:45:29 +1000
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> 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] On Behalf Of James Hunt
> Sent: Wednesday, 20 April 2011 11:52 PM
> To: 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
>
> To unsubscribe, send a message to 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
>
> To contact the list administrator, send a message to
> austechwriter-admins@xxxxxxxxxxxxx
> **************************************************
>
> **************************************************
> To view the austechwriter archives, go to
> www.freelists.org/archives/austechwriter
>
> To unsubscribe, send a message to 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
>
> To contact the list administrator, send a message to
> austechwriter-admins@xxxxxxxxxxxxx
> **************************************************
>
--
Bob Trussler
Phone 0418 661 462
Other related posts:
