Word Considered Harmful

by Eric M. Burke

People like Microsoft Word. It is easy to use and widely available. So you end up working on teams where lots of technical documents are created as Word documents. Things like project standards, procedures, tutorials, use cases, requirements, meeting minutes, etc.


I contend that project-related documentation should be designed for easy collaboration. Word documents are easy for the original author to create, but lousy for collaboration.

Some technical complaints...


Word docs are binary. This means they don't play well with version control tools. It is next to impossible to determine what changed between successive revisions of binary files. You also end up in situations where only one person at a time can update the document. If concurrent edits occur, you have to merge changes manually.


Word docs are slow. When documentation lives in a web site, you just click on hyperlinks and view HTML in your browser. Although you can embed links to Word docs in your HTML, those docs can get quite large and take too much time to load.


Linking is lousy. With HTML, you can cross-reference docs quite easily. Word docs are much more self-contained, making it very difficult to cross reference a specific portion of a given document.


Searching is lousy. As you build a library of project documentation, how do you search for information when it is scattered across lots of isolated Word documents?


etc...I could really come up with a lot more reasons why the most popular documentation tool introduces lots of problems, but I'm running out of time. So here is an alternative.

Another option


I believe tools like TWiki offer an excellent alternative to Word documents for many kinds of documentation. I suspect that most non-technical people haven't been exposed to Wikis and don't know what they are missing. Why not set up a Wiki for your next project and see how it goes?


NOTE: I'm picking on Word, but this same set of arguments is equally applicable to any word processor. While word processors are good for creating formatted documents easily, they are not the best choice for creating a "web" of easily accessible and maintainable project documentation.


12 Comments

jimphelps
2003-09-24 10:34:02
Interesting thoughts.
I was actually working on a piece that I call, "Collaboration in a Tool Rich Environment". You discussion about why Word (or other proprietary / binary document solution) is bad is an interesting addition.


http://arch.doit.wisc.edu/jim/log/index.cgi/Thoughts/collaboration.html


I would like to add your ideas and point to your article as I explore the collaboration tool space further.


- Jim

burke_e
2003-09-24 11:04:27
Interesting thoughts.
Feel free to do that. You might also want to check out "The Pragmatic Programmer" by Andy Hunt and Dave Thomas. They have a good discussion on the merits of text formats versus binary.
anonymous2
2003-09-24 12:43:24
TWIKI an excellent alternative?
It has its drawbacks
- formatting medium to large documents is cumbersome
- embedding arts & graphs
- repetitive Edit & Preview cycle
- could benefit from a standalone editor(rather than a browser) which can then upload the page


and probably some more...

gbshuler
2003-09-24 13:08:07
Other thoughts..
Many groups I have worked with like to pass huge Word docs around using an email client. In these virus crazed days, the last thing I want to receive as an attachment is a .doc file. Give me flat file or WiKi any day over that.


Another problem I have seen is when people of differing skill and knowledge levels get their hands on the document and modify to their hearts content. One person adds an advanced feature. Another deletes something important and doesn't even know it was there. No matter what happens.. any time a Word doc gets edited by more than three people, bloat starts to creep in.


An example.. a department publishes a mammoth 200 page .doc file containing all standards everyone is supposed to follow. Every week they change a line or two somewhere, or add a page in the middle and make a big announcement (spam) to everyone. I call this spam because only the people affected by a change should be notified.


As a software developer used to easy, GUI based version control I just can't bring myself to open the document. I assume no one else on the project does either..

anonymous2
2003-09-24 14:45:33
Another wiki problem: output
Wikis are great for capturing and linking information. But because of their non-hierarchical nature they're terrible at outputting in the way we humans are accustomed to. And most people are fundamentally used to reading large quantities of text in hardcopy. Where's the middle ground? (Is there one?)
otto
2003-09-25 05:48:16
What about LaTeX?
Wikis are great, but one thing I expect from technical documentation and the like is structure - and that's what wikis lack.


I know that LaTeX isn't for everyone, but since the documents are plain text, there's no problem with version control and diffs at all. You can also produce PDF, HTML, DocBook and what not from LaTex easily with standard tools.


I guess somebody should try to get wiki and LaTeX to work together, e.g. parse the wiki homepage and include each linked page as a chapter.
Any ideas?


Cheers,
-otto.

anonymous2
2003-09-25 09:06:27
An easy to setup Wiki
Why not setup a Wiki for your next project? You mean because most of them (like Twiki) are a nightmare for most people to setup (and often to use). I think that's one big reason they're not used more.


ProjectForum is one that anybody can setup immediately (just runs as a regular application, no hacking scripts, installing databases, etc.). See http://www.projectforum.com/pf/

anonymous2
2003-09-25 09:47:07
Word very harmful ...
Being a technical writer who has had to use Word in the past, I can tell you how harmful it is. From templates being corrupted to Word's poor handling of large documents, to its crashiness ... Suffice it to say that for serious documentation tasks, Word doesn't cut it. FrameMaker and DocBook are my preferred authoring tools, with supplementary tools like WebWorks and RoboHelp to generate Help in various formats. OK, I do use LaTeX for some things, too.


But I do have to disagree with the author about using a Wiki. I find Wikis useful for disseminating information, but what about output? Using DocBook or Frame, I can generate the stuff that users (should) read -- PDFs, online Help, and HTML-based documentation -- quickly and easily.

crazybob
2003-09-26 09:07:49
SnipSnap
We've had good experiences with SnipSnap. It was painless to install, and the templates look really sharp and professional. Plus, it's a blog and wiki in one, and it supports creating graphs.
anonymous2
2003-09-30 01:56:38
Been there, done that
I did a collab project in word once, in 95/96 I think it was. Nuff said :) For the last five years, I've used latex most of the time. Works pretty good, add cvs to the mix, and you have a pretty spiffy system. Changelogs, version control, easy to see who did what, etc.
anonymous2
2003-10-09 19:26:35
Another wiki problem: output
>> non-hierarchical nature


Have you checked out Zwiki.org ?

anonymous2
2003-10-09 19:27:51
What about LaTeX?
Check out:


http://mcelrath.org/Notes/LatexWiki