Author Archives: grenley

The Drawbacks to DITA

Leave a reply

Does DITA have drawbacks? Yes, of course.

  • It’s more complex than most typical wiki makeup languages. To some extent, this is a reflection of its power, but it also means that casual users can really hurt themselves.
  • DITA output must be created – compiled, in effect – using some fairly complex compilers. Again, this is to some extent the source of DITA’s power, but it also means that you need a person skilled in developing and maintaining the DITA compiler.
  • You are going to have hundreds of DITA files, so you are going to need some sort of source-code repository system. This can be GIT or SVN, but you may need more.
  • DITA is very aware of the ‘elements’ within each DITA topic, so to get the full advantage of DITA, you need a way to track and manage element IDs. Content Management systems exist to do this, but they are expensive and require their own level of expertise.
  • So-called DITA-aware editors are available, but many of them cost several hundred dollars per seat. (There are plug-ins for Eclipse that handle DITA fairly well, and are free.)

Should your organization be using DITA? It depends on your goals and needs. We’ll dig into this in the next post.

 

The Advantages of DITA

Leave a reply

In our last post, “Do You Need DITA?”, we looked at what DITA was. Next, we will look at its advantages.

  • It’s probably the best method available today for creating content that needs to appears in different formats, e.g. PDF, web, mobile, etc. Commands are available to choose between long-form and short-form names based on the available display area. For example, a pop-up might say simply “DITA”, while a PDF might say “Darwin Information Typing Architecture (DITA)”
  • It reduces translation costs. Because it is extremely modular, only changed DITA files need to be re-translated. Updates to the primary-language content (e.g., English) trigger translation only for files that have changed. Furthermore, DITA supports certain types of do-not-translate and lock functions, to further minimize the amount of translation to be done.
  • It supports content re-use. Several techniques are available to let you standardize chunks of content, (e.g. notes and warnings, boilerplate) and yet also customize re-use. For example, a set of instructions common to a range of products can be written once, with specific product nomenclature added automatically.
  • It is highly structured, and more-or-less forces authors to follow specific templates and structures. You cannot, for example, digress into theory in the middle of a sequence or steps.
  • Each ‘element’ in DITA content has an identifying label. This gives you very fine-grained control of content re-use. (An element can be a simple as a word or phrase, a step, a figure, a sequence of steps – almost anything, really.)

Are there drawbacks to DITA? Yes, of course. But that’s a topic for our next post.

Do You Need DITA?

Leave a reply

DITA, the Darwin Information Typing Architecture, is an XML-based system for creating content that can easily be re-purposed for multiple output formats, that is, PDF, web, mobile, etc. Quite a few companies are using it. Should yours be one of them? This series of blog posts will look at the pros and cons of DITA.

What Is DITA?

DITA can be described as a strongly-typed language for expressing technical content in a highly modular way. It is semantic in nature; its meta-data describes the nature and purpose of all content, rather that how that content is to appear. In this regard, DITA is somewhat similar to DocBook, and different from HTML and most Wiki or web markup languages.

DITA strongly encourages you to write small, modular “topics”, then create your content by linking topics together using “maps”. Numerous conditional-compilation and output-format-specific options are available.

NEXT: The “pros” of DITA

Banished Word: “It’s in Our DNA”

Leave a reply

Time to retire this cliché.

It is not “in your DNA”. You don’t get to vote about what’s “in your DNA.” You certainly don’t get to change, at the whim of the marketing department, what’s “in your DNA”.

There’s a good chance that what is in your DNA is as lovely as cystic fibrosis, Tay-Sachs’s Disease, or sickle-cell anemia. Especially if you are a large organization.

So knock it off!

Jawbone Shows How Customer Service Is Done

Leave a reply

Now this is great customer service!

Jawbone apparently had some technical issues with early versions of their new UP health monitor. Did they hide behind lawyers? No. They stepped up and did the right thing. Read the letter from the CEO, below. It’s great customer service – far above what you’d expect!

Jawbone understood that p*ssing off the early adopters would kill the product, and maybe the company. Why don’t more companies know this? Does yours?

 

LETTER FROM THE CEO

  • THE UP™
  • NO QUESTIONS ASKED
  • GUARANTEE

To the UP community:

Earlier this year, we unveiled Jawbone’s vision to help people live a healthier life with UP. We’ve been thrilled by the passionate response to this product. We heard from tens of thousands of you through emails, tweets, blog posts and on our forums about how you’re changing your lifestyle and becoming consumers of your own health. In just four weeks, UP users have collectively taken over three billion steps, gotten more than 300 years of sleep and captured hundreds of thousands of meals.

While many of you continue to enjoy the UP experience, we know that some of you have experienced issues with your UP band. Given our commitment to delivering the highest quality products, this is unacceptable and you have our deepest apologies. We’ve been working around the clock to identify the root causes and we’d like to thank everyone who has provided us with information and returned their bands to us for troubleshooting. With your help, we’ve found an issue with two specific capacitors in the power system that affects the ability to hold a charge in some of our bands. We’re also fixing an issue with syncing related to the band hardware. Typically, these issues surface within the first seven to ten days of use. The glitches are purely performance related and do not pose any safety risk.

We’ve also received helpful feedback on the application experience, including bug reports, ways to make signup and finding friends easier, user interface suggestions and new feature requests. Your comments are invaluable as we continue to improve, so please keep them coming and check back frequently for updates to ensure you’re always enjoying the latest features and enhancements.

We recognize that this product has not yet lived up to everyone’s expectations – including our own – so we’re taking action:

The UP No Questions Asked Guarantee

This means that for whatever reason, or no reason at all, you can receive a full refund for UP. This is true even if you decide to keep your UP band. We are so committed to this product that we’re offering you the option of using it for free.

The program starts December 9th and full details can be found at http://jawbone.com/uprefund.

For most of you, this program is simply meant to offer peace of mind. Please continue to enjoy your UP band and keep sharing your experience with us. If you encounter any problems with your UP band, contact Jawbone directly for your choice of a replacement and/or refund under this program. It’s that simple.

Jawbone remains deeply committed to addressing all issues with UP, investing in the category and giving our customers the tools to live a healthier life. We’ve temporarily paused production of UP bands and will begin taking new orders once these issues have been sorted out. In the meantime, we’ll continue to release app updates for existing users.

We regret any disappointment we’ve created for our community of users and appreciate the trust you’ve put in us. The fact that you’ve taken the time to talk with us and help us make a better product is simply phenomenal. Our customers have always been part of our team and we’re incredibly grateful for that.

Please know that we’re doing – and will continue to do – everything we can to make things right. This is just the beginning for UP and we are excited to keep improving until we realize the powerful vision of what this category can be.

If there is absolutely anything else we can do for you, please let us know.

Hosain Rahman
CEO
Jawbone