Collaboration
Posted December 31st, 2004 @ 03:45pm by Erik J. Barzeski
I'm going to be collaborating with someone on a book-writing project soon. Final copies of the book are to be submitted in Microsoft Word (an app that I despise for the most part). The book will have code, images, captions, prose, and chapters, footers, etc. A normal computer-related book. The content of the book is unimportant as far as the question: What's the best way to collaborate on such a project?
We could write everything in Nisus Writer Express, but their "tools in a drawer" trick makes me gag. We could write everything as HTML and convert to Word later, but any sort of markup would impair readability (and editability). No WYSIWYG editors I'm aware of produce very good code. LaTeX is out, so don't suggest it. It's a major PITA.
So, what to do?
(Brief aside: there is probably a market for an application that can do the above. I won't be writing it. I'll probably be too busy fucking around with Microsoft Word. I really would just like to hear people's suggestions for now.)
Donate Life
Posted 31 Dec 2004 at 3:57pm #
Did you think about LateX? It's plain text and you can convert it easily to many formats.
Posted 31 Dec 2004 at 3:57pm #
It's sort of too bad that you rule LaTeX out, since it's perfect for what you're doing, and can be used to make beautiful books.
That aside, why don't you try something like DocBook? Which enough line-spacing it should work nicely in a Subversion repository.
Posted 31 Dec 2004 at 4:08pm #
I am interested in figuring out a solution to this same problem. A work project I am on needs to produce an end-of-project book that will have at least three coauthors. How do we coordinate the writing between the authors, especially when we will go through editing cycles and have some commonly worked on chapters.
I am a huge proponent of LaTeX for doing all sorts of writing, and I went through grad school and previous jobs using it. However, none of the other coauthors are familiar with LaTeX and corporate policy mandiates Word documents be sent to the publication office. While I wish there were different options, there is little choice.
Posted 31 Dec 2004 at 4:14pm #
I'm also interested in finding a nice OS X tool for writing structured documentation; something that can smoothly output a number of formats -- i.e. Word, PDF (with hotlinked table of contents), HTML, etc. I've heard that FrameMaker would be an ideal tool for this purpose, if an OS X version existed.
If someone wrote a usable WYSIWYG tool for creating LaTeX documentation (and packaged it as a *single* tool, not dependent on a load of other utilities), I'd probably take a closer look.
Posted 31 Dec 2004 at 4:58pm #
Future comments that don't address the question but instead talk about how cool it'd be to have an application that did this will be removed.
I agree that it'd be a great application, but I'm looking for a solution now. Not in a year.
Posted 31 Dec 2004 at 5:51pm #
I like the suggestion about putting it in an subversion (or CVS, for that matter) repository. DocBook allows you to export to Word, or so I thought.
One could use a application that wrote to a XML based format. OpenOffice/NeoOffice might work, if you can stand it. Abiword might work too (although I've heard reports that it's crashy now.)
Or you could grin, put up with Word, check it into subversion, deal with it, and hope you don't conflict. (CVS too, but I'd be very scared of $Id$ tags etc.
Posted 31 Dec 2004 at 7:24pm #
I'm absolutely not a fan of MS products and I have personally seen Word on Windows destroy final diploma report documents on the day they were due, but I used Word on three such collaborative book projects by now and I have to say that it worked fairly well all the time, especially if you stick to using style sheets religiously (which is how any word processor should be used anyway). The "track changes" feature works very well too for collaborative work.
In these book projects, we had to use templates with style sheets predefined by the publishers. We were sending word files back and forth via email (good subject lines help to organize it). Sometimes we used iChat to coordinate or discuss things.
Personally and at work, I now use OpenOffice (with its native document format, not its .doc compatibility filters) for all long, hierarchically structured documents that I write. This might be something for you, because you could convert to native MS Word file format at the end to get the required output.
OpenOffice gives me complete freedom to reuse the content because of OpenOffice's native XML format and its XSLT import/export filters. I am working on a module that allows me to convert embedded POD documentation in Perl source code directly into a new chapter in a larger OpenOffice document, complete with code sections, different heading levels etc.
Its numbering works much more predictable than Word's too. The user interface sucks, though... One killer feature that is missing there is the ability to assign keyboard shortcuts to style sheets, like the built-in Cmd-1 / 2 / 3 in Word for Heading 1-2 for example.
Posted 31 Dec 2004 at 10:05pm #
It doesn't answer your question, but I'd like to second (or is that third?) the Subversion comment. I use Subversion repositories for almost anything that might benefit from storing a couple of version generations of the project, be it code or documents.
It's also great to sit down at some other computer and check out the latest version from the internet if you didn't bring it with you.
Posted 01 Jan 2005 at 8:37am #
I would propose following solution:
Use DocBook-XML with an WYSIWYG-XML-Editor like Syntext Serna or XMLmind XML Editor.
You can use Subversion as SCM and merge the commit logs into the DocBook book using XSLT.
See Microsoft Word just as another target of deliverables. Using the DocBook-XSL-Stylesheets and the XMLmind FO Converter you can create RTF output. Open this file in Microsoft Word and save it as Microsoft Word DOC, and you are done. Another option could be to postprocess the XSL-FO output with the FO-to-WordML stylesheet and open it in Microsoft Word 2003 or you take the direct way and use the DocBook to WordML XSLT stylesheet.
Posted 01 Jan 2005 at 8:41am #
DocBook for collaborative writing
Question:
I'm going to be collaborating with someone on a book-writing project soon. Final copies of the book are to be submitted in Microsoft Word (an app that I despise for the most part). The book will have code, images, captions, prose, and chap
Posted 01 Jan 2005 at 12:34pm #
if the publisher wants the thing to be in Word, then I'll say use Word. For one, especially with 2004, the track changes stuff is much improved. Shunting the change tracking to bubbles on the side and not making hash of the layout is quite sweet.
Style sheets are your friend. Do not deviate from them. Use them, live them. You'll be happier in the end. Having just worked on a project where the other author insisted that Open Office would work, no, not yet. Maybe with version 2 of OO, but the current version made utter hash of the template and style sheets.
One thing that can help is if the styles get confused, try selecting the confused text, hitting it with the "clear formatting" style, then hitting it with the correct style.
The biggest issue with word is it's file format which is far more complex than it should be, but also designed about ten years ago, when there was nothing better. Hopefully, the next release of Office will bring Word and PowerPoint to where they can work in XML the way that Excel can.
john
Posted 01 Jan 2005 at 4:52pm #
Have you looked at Mellel?
Erik
Posted 02 Jan 2005 at 1:16am #
you ask a solution, but you rule out latex from start, it's weird. because it is the solution many people use in university for create numberous texts.
if you are serious and professional about text editing latex is the tool made for THAT ! you young fools (just a joke, but I'm serious for latex)
latex is not a toy neither quantic science, it's professional and academic tools from many years.
else, if want to go the all xml way : go to docbook. it's based text (so reliable), easy to collaborate and there are many tools to transform it in all formats you want
free or commercial tools.
and no, it's not hard and very powerful and open to many final format.
Posted 02 Jan 2005 at 1:48pm #
A little known secret is that Word will import HTML almost as if a native document. It maps CSS class attributes to its internal style system.
In my experience, when publishers insist on "Word", they're really asking for a document they (well, usually their editors) can open in Word. DocBook -- with its rich XSLT support -- is thus a good choice. There's even the beginnings of DocBook --> WordML stylesheets (see google).
I like TeX output quality, but that's not really the issue here. Interoperability is, and XML/XSLT is a better tool for that than LaTeX.
Posted 02 Jan 2005 at 6:18pm #
In my experience, when publishers insist on "Word", they're really asking for a document they (well, usually their editors) can open in Word. DocBook -- with its rich XSLT support -- is thus a good choice. There's even the beginnings of DocBook --> WordML stylesheets (see google).
Actually, the publisher's I've worked with, Prima, Peachpit and Wrox are pretty clear..they want Word, specificially the templates they sent you. If you have to send in your work in Word, why add three or four steps in via a conversion process that you have to doublecheck in Word anyway
Posted 03 Jan 2005 at 6:51am #
As others have said, this is simple: You use styles and Word's track changes feature. That's how both books I've worked on were done, and both went rather well (from the using-Word standpoint, at least).
Posted 03 Jan 2005 at 2:03pm #
I find it incredibly presumptuous of anyone to tell me what tools to use. If a publisher told me I must submit .doc files, I would use another publisher.
In my case, the publisher I'm currently working with actually does hard-copy proofing. I author in emacs in conjunction with a CVS repository these days, and unlike with Word (which would regularly crash on me), I never worry about losing data.
YMMV of course.
Posted 03 Jan 2005 at 4:16pm #
Have you thought about using SubEthaEdit? It's very, very simplistic, but I've found it useful in situations where collaboration is required. Granted, I've never collaborated on a project as large as a book (at least, not all at once).
The only way you could really do the layout with it is HTML, but if nothing else, you could use it for looking over and editing each others text and then do the layout later.
Posted 03 Jan 2005 at 4:47pm #
Question: Which Omni Group products do you own? My Answer: OmniGraffle Pro and, uhhh, OmniOutliner 2.x. I had a student license to OmniWeb 3 or 4, but OW5 hasn't impressed me in the least. I may pick up a copy...
Posted 03 Jan 2005 at 8:02pm #