Solving Word’s Problems… by ditching Word.

So I’ve previously discussed a series of problems Microsoft Word has, and as Josh rightly pointed out, we’re using a tool that wasn’t made for what we’re using it for. :) Thus I began hunting for a new method of writing documentation.

Here were my requirements:

Must Have:

  1. Must support multiple users editing the same file at the same time.
  2. Must handle cases where two users edit the same content into two different results. It must do this without crashing or deleting someone’s data.
  3. Must be able to show me who made a change to the document, exactly what they changed, and when they made it.
  4. Must be easy to edit by someone who doesn’t make documents for a living. AKA, one of our software devs should be able to make a spec, manual, or test procedure change without having to spend 20 hours in training to learn a tool.
  5. Must be able to make outlines, align and resize images, tables, and other standard MS Word features.
  6. Must be able to handle cross-referencing in a clean and friendly way for things like Tables of Contents, Tables of Figures, Indexes, Page Numbers, and Footnotes.
  7. Cross-referencing must be able to handle local links and not demand a full path.
  8. Must export to PDF.

Nice to Have:

  • Content should be separated from layout and design. I should be able to write text in Notepad, then parse it through a stylesheet and have it format a beautiful PDF for me.
  • Content should be able to be exported to PDF, CHM, HTML, DOC, and ODF. LaTeX would also be awesome.
  • Look and feel should remain similar across all exported formats.
  • I should only have to write one Manual for all of our similar products, then input a code that says “only include content in this manual for versions X and Y”.
  • Should be free, both as in beer and as in freedom.

You’d be surprised how hard this hunt was. See links below for more information.

  • Adobe FrameMaker: Fails requirements 1 and 4.
  • QuarkXPress: Fails #4, but surprisingly handles #1 really nicely.
  • DocBook with a CVS: A personal favorite of mine, but it fails requirement 4.
  • Scribus: Fails requirements 1 through 4.
  • LaTeX with a CVS: Fails requirement 4.
  • WIKI: Fails requirement 8. So close and yet so far.

After reviewing all of these heavy hitters, I was dismayed at how many of them would fit my needs if I could remove requirement 4. It was around this time that I discovered my new friend: ReStructuredText.

It uses plain text (.txt) documents that are pushed through a CSS-like stylesheet parser. Outputs to PDF, HTML, LaTeX, and others. I’ve found I like the extra tools available in the RST2PDF extension, as it handles cross-references and 8 1/2 x 11 layout better. Combine this with a standard CVS like SVN or DCVS like Git, and you’ve got an extensible markup language that’s multi-user friendly and easy to learn.

Example:

This text file: http://docs.python.org/_sources/whatsnew/2.7.txt

Produces this webpage: http://docs.python.org/whatsnew/2.7.html

Wow!

I’ll go into more detail about how I’ve set up my RST forge in another post. :)

About these ads
  1. #1 by Joshua on January 7, 2011 - 2:34 PM

    Hmm… RST looks like a neat thing. I’ll have to play with it a bit when I have time.

  2. #2 by Andrew on January 9, 2011 - 7:31 PM

    I am still always amazed how many amazing things you can find on Sourceforge. I found a great one during lunch last week to help me deal with databases of information that I deal with on a weekly basis.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 48 other followers

%d bloggers like this: