Archive for April, 2012

Want to be more productive when you blog?

Thursday, April 19th, 2012

Interesting piece for those who blog…
The 7 Bad Habits of Insanely Productive People

The 7 Bad Habits of Insanely Productive People

“The New Yorker”‘s defense of comma usage

Friday, April 13th, 2012

A lovely brief piece on why TNY uses commas the way that it does.  (The “comma shaker” is a hoot!)


Review of “DITA 101: Fundamentals of DITA for Authors and Managers”

Wednesday, April 11th, 2012

DITA 101 Fundamentals of DITA for Authors and Managers

DITA 101 identifies itself as providing the “Fundamentals of DITA for Authors and Managers”. And to a certain extent, it does just that. It is a short book and a quick read, and provides a lot of information about DITA in a very readable format. It is worth having on your bookshelf, but if you are considering working with DITA (or are already); you will need a bigger book to sit beside it.

Let me start with what I did like about the book. It is short (160 pages overall), the writing is generally clear, with uncommon or specific-meaning terms usually explained, and the examples (where provided) are clear. The basic page layout is good, with room in the margins for annotations and a legible font set. The first 30 pages provide a good clear review (one of the best I’ve read) of DITA and its value.

However, this book frustrated me immensely as I read it, as it desperately needed a good structural and design edit. The chapters are often transparent (the only way to know that you have changed chapters is to check the header), and the cross-references are often ambiguous (Figures restart numbering for each chapter, but are only referenced by the figure number) or missing. If I was reading a pre-press edition I might cut the authors some slack on this, but in a published second edition, these are unacceptable.

In addition to ambiguous boundaries, the chapters suffered from a lack of clear navigational structure. I did not know in advance what information I would (or would not) find in the chapter. There are headings, but only two levels were visually distinguishable, and that is not enough for a book as technical as this.

As seems to be typical of books about DITA, the authors imply that it is only suitable for large corporations who can hire a team of people to create documents. As a lone writer, I have often wanted to make the conversion to DITA to save me all the over-writing and problematic reuse (“Did I put that really good description in chapter 4 or chapter 7?”), along with the overhead of creating multiple output formats and translation. There is a decent but minimal exploration of DITA cost savings (but no estimate — even an order-of magnitude one) of what a DITA implementation will cost in time or money.)

The real problem I have with this book (and I *wanted* to like it, as I have great respect for the authors) was that when they got into the meat of working with DITA, they began assuming more knowledge (and more technical knowledge) on the part of the reader, without providing any support structures such as internal or external references, and using fewer and fewer code samples. (As an aside, I found it problematic that the samples use tags that are neither part of HTML nor in their list of supported DITA tags (for example: PH and TGROUP). This problem gets exacerbated as they skimpily touch on the tools to create and work with DITA (the only one mentioned is the very basic DITA Toolkit), briefly glance over the relationship between a CMS and DITA, and effectively ignore the issues and challenges of producing well-formatted output. Their answer to this last? “Hire a pro”, which is not exactly useful, even if it may be correct.

The book closes with a brief overview of DITA 1.2 (Approved in December 2010), a very high-level quick reference to DITA 1.1 tags and topics, a history of DITA, short bios of the authors, and a 5-page (single column) index.

ISBN Info: ISBN-10: 0557072913   ISBN-13: 978-0557072910

An excellent writing reference site

Tuesday, April 3rd, 2012

Created and maintained by Ann Gordon.

I don’t know why I haven’t found it before now!