Author Max: Great DITA, Great Documentation

Is Markup Mentoring for Me?

Posted in DITA, Minimalism, Technical Documentation, Uncategorized by katriel on the February 7th, 2013

Ongoing content audits, or – as we prefer to call it – markup mentoring bridges the gap from your DITA plan to your DITA implementation.  Semantic markup mentoring will increase the effectiveness of your DITA content, reduce long term maintenance costs for content, and enable support for the fullest range of current and future publishing needs.

In the information architecture stage a  lot of thought is given to a range of factors, including:

  • what topic types should be used (machine industry tasks or strict task topic types, for example),
  • what specializations may be needed (<sku>?, troubleshooting topic?),
  • selecting semantically appropriate tags (<menucascade> and <uicontrol>),
  • choosing elements that will enable fastest content creation and best presentation (<dl>, <table>, within an image, <title> or <desc>, nesting <ul> within <p), and more),
  • enabling reuse (through appropriate use of variables, keyref, conref and more)
  • applying conditions to enable focused content limited to “need to know”, without destroying writer productivity
  • developing a related information approach using relationship tables and other mechanisms
  • planning for minimizing translation cost and enabling pain free translation

Markup mentoring will help you and your writers successfully bridge from information architecture to robust semantically correct markup. The bottom line: we recommend markup mentoring to get the best results from your DITA implementation.

Not DITA, but so cool that I just have to post!

Posted in Uncategorized by katriel on the January 10th, 2013

Hi All,
This is not strictly DITA, but it’s just so cool. Our GoMDweb division continues to grow and this month posted sites for two new types of health care providers.

Dr. Marc Krauss practices in Long Island, providing both psychological counseling and testing for students. With offices in Cedarhurst, NY, Dr. Krauss also provides online therapy. … Find out more about Dr. Marc Krauss. (If you’re a health care provider. click here if you want to know how you can start to provide online therapy.)

Dr. N. Alan Toporovsky delivers personal and attentive dental care to people confined to their homes or in-patient facilities. The Homeward Bound Dentist makes dental house calls in New York City, Long Island and Lower Hudson Valley. Click here to learn more or to make an appointment for home or in-residence dental care.

Machine Industry Task

Posted in Uncategorized by katriel on the January 10th, 2013

Are you using the machine industry task? If so, I would love to hear from you.
We are recommending that a customer adopt the machine industry task as their standard task topic. We have considered some of the implications for efficiency for those tasks where not all of the tags are needed, but are still convinced that having the extra elements will keep the content semantically more meaningful.
! Katriel

Is an information architect really needed?

Posted in Uncategorized by katriel on the November 14th, 2012

Stimulated by a discussion in the DITA Metrics group on LinkedIn about the value of information architects, here is a quote from Frank Lloyd Wright:

“…go as far away as possible from home to build your first buildings. The physician can bury his mistakes,—but the architect can only advise his client to plant vines.”  (From a lecture published in 1931, To the Young Man in Architecture. Thanks to the Quote Investigator.)

So, if you are moving jobs soon, changing careers or getting ready to move out of town under an assumed identity, don’t worry about implementing DITA without an information architect.  But if you plan on sticking around for a while and living with the consequences of your implementation, get an architect!

The DITA Project #17: Considerations for using using conditions in a conref

Posted in Uncategorized by katriel on the September 11th, 2012

When the content of your conref needs to change — as in for different audiences or for different products — conditions enable your conref to adapt!

You should, however, consider using conkeyref (for large reusable chunks) or using keyref (for smaller reusable chunks, such as a product name or other string that fits neatly in a <ph> element).

Now available in Kindle

Posted in Uncategorized by katriel on the June 18th, 2012

Who isn’t going mobile now for content delivery?  Supplying content for desktops is like manufacturing typewriter ribbons.  Even our family favorite for bedtime stories, The  Adventures of Shainy and Brainy, is now available in Kindle from Amazon.

OK, I may have exaggerated.  Paper isn’t going away totally.  But if you want to be in front of your customers, then you need to get available on smartphones, tablets and eReaders.  You may need to support a proprietary format for Kindle or you might choose the HTML 5 route (our preference where feasible), but you need to move ahead.  Call us to discuss if you like!

The DITA Project #5 choices or choicetables?

Posted in DITA, Minimalism, Technical Documentation, Uncategorized by katriel on the November 9th, 2011

Why use <choices> or <choicetables> instead of <ol> or <ul> in a task topic when you need to choose what to do next?

The benefit is that the markup is semantic! When you use <choices> or <choicetables>, the machine (and the writer!) understands explicitly if we are talking about:

  1. <choices> where the customer has reached a decision point and must choose one of the options (such as,  take Route 66 to Boston or Route 81 to Ithaca).
  2. <choicetable> — where the customer has different options to get to the same result (such as CTRL+S or File > Save).

Using <ol> or <ul> eliminates semantic markup! Using <choices> or <choicetables> explicitly indicates the kind of juncture the reader has reached — and forces the writer to state if no matter what the choice, the end result will be the same (<choicetable>), or if the choice selected will lead to a different outcome (<choices>).