Thanks, Ken. What I?m wondering is if someone has made DITA (or another tool that achieves the same thing) user-friendly, such that you don?t need to be too IT-literate to use it. In a lot of the places where I?ve worked, some text (such as a safety warning) is re-used in several documents. When changes are made to the wording (as invariably happens), it becomes a labour-intensive nightmare to update the myriad of documents containing that text. Or, for example, if the company is taken over by another, and logo changes are required on all documents, can document management systems automate that change? I?m wondering if there is a product out there that does these sorts of things, or whether someone needs to create one. Because so many people are relatively comfortable with MS Word, it seems to me that the system should at least ?appear? to work like Word, but with added features. Rosemary O?Donoghue TechWriting Clarity out of Complexity Mob: 0419 24 3636 rosemary.odonoghue@xxxxxxxxx www.businessprocesswriting.com _____ From: austechwriter-bounce@xxxxxxxxxxxxx [mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of Ken Fredric Sent: Wednesday, 27 April 2011 5:58 PM To: austechwriter@xxxxxxxxxxxxx Subject: atw: Re: Replacing Word (Long...) Try Wikipedia first for an overview: http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture Cheers, Ken. _____ From: austechwriter-bounce@xxxxxxxxxxxxx [austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of Rosemary O'Donoghue [rosemary.odonoghue@xxxxxxxxx] Sent: Thursday, 21 April 2011 4:57 PM To: austechwriter@xxxxxxxxxxxxx Subject: atw: Re: Replacing Word (Long...) Ken, Tell us more about DITA Rosemary O?Donoghue TechWriting Clarity out of Complexity 9B Dobson Crescent Dundas Valley NSW 2117 Mob: 0419 24 3636 rosemary.odonoghue@xxxxxxxxx www.businessprocesswriting.com _____ From: austechwriter-bounce@xxxxxxxxxxxxx [mailto:austechwriter-bounce@xxxxxxxxxxxxx] On Behalf Of Ken Fredric Sent: Thursday, 21 April 2011 11:47 AM To: 'austechwriter@xxxxxxxxxxxxx' Subject: atw: Re: Replacing Word (Long...) 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> 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 -------------------------------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. -------------------------------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.