Author Max: Great DITA, Great Documentation


The DITA Project #18: markup for choosing from a drop down list

Posted in DITA, Minimalism, Technical Documentation by katriel on the October 29th, 2013

Some guidelines for which DITA elements to choose when the user has to choose from a drop down list (or radio button or similar).

Always choose a specific item from the drop down list

If the procedure will direct the user to always choose a specific item from the drop down list, use <uicontrol>. For example, if your product always has a local server even though the drop down menu offers an array of choices (local server or remote server):

<step>
<cmd>Click <menucascade><uicontrol>Server Configuration</uicontrol><uicontrol>Local server</uicontrol></menucascade>.</cmd>
</step>
Comments Off

We Love The Machine Industry Task

Posted in DITA, Minimalism, Technical Documentation by katriel on the October 24th, 2013

Back in January we were still a bit unsure if the added complexity of the <prelreqs> element in DITA Machine Industry Task topics were worthwhile.

Ten months later, with hundreds and thousands of machine industry task topics under our belt, we are no longer on the fence. In fact, our default recommendation now is to use machine industry task topics by default, rather than the standard DITA strict task topics. (In DITA 1.2, strict DITA task topics are the good old fashioned task topics that you know and love.)

Caveat:
Unfortunately, out-of-the-box machine industry task topics are missing some key elements (such as <userinput>), so we have specialized the machine industry task topic type to make it more functional for most needs.

Comments Off

DITA Right-to-Left Characters in oXygen 15.1

Posted in DITA by katriel on the October 10th, 2013

Kudos to the folks at SyncroSoft for implementing support in <oXygen/> 15.1 for right to left (RTL) languages. Support works quite nicely out of the box for content creators, editors and for publishing. Using the dir attribute you can control display in author mode as well as publishing.  (Display of punctuation for RTL in text mode is still tricky!)

What it Means for DITA Authors

This means that DITA users can easily create and edit DITA content in Arabic, Hebrew, Persian, Urdu and other right to left languages. You can mix content in left to right and right to languages in a single topic.  By the way, if you’re curious about what other languages go from right to left and require bidrectional support in DITA, you can click here for a list of right-to-left languages.

The Oxygen XML Editor implements the Unicode Bidirectional Algorithm as specified by the Unicode consortium. The text arrangement is similar to what you get in a modern HTML browser. The final text layout is rendered according with the directional CSS properties matching the XML elements and the Unicode directional formatting codes.

What You Need to Set

To control display in output set the dir attribute on an element containing right to left characters.

For example: <p dir=”rtl“></p> would define the paragraph as right to left.

Need More Help for DITA?

Feel free to call or contact MethodM for any help that you might need with DITA. We are expert at DITA implementations, training, content audit, specializations, transformations and more.  Looking forward to hearing from you soon!

<p dir=”rtl”>שלום
כיתה א’.</p></context>

When Should I Start Markup Mentoring?

Posted in DITA, Minimalism, Technical Documentation by katriel on the August 13th, 2013

Q. When can/should your team start markup mentoring? (Markup mentoring is sometimes referred to as a DITA audit or DITA tagging review)

A. As soon as your writers start working on DITA content, even with just a small amount of content that you might have for a pilot project.

As writers start working on DITA they will quickly adopt DITA authoring/editing habits – and it’s critical to get “best practices” ingrained from the get go.  It’s more effective, easier, better and fun to go with best practices than slip into bad habits* and then have to unlearn them.

* Bad habit = markup that is not semantically meaningful or is hard to maintain

Q. How much content is needed before it makes sense to start?

A. Start as early as possible, before lots of content accumulates and “sunk costs” (or, in this case, “leaden content”) becomes an issue.  This should be done from Day 1!  If you have already started creating DITA content, the earlier you start markup mentoring the more effective your implementation will become.

Is “semantic markup”, or correct tagging, really important?

Posted in DITA, Technical Documentation by katriel on the August 6th, 2013

“Semantic markup” sounds kind of esoteric, but it’s not. Correct use of DITA elements is an investment that will pay off rapidly in terms of usability, maintenance and support for all kinds of deliverables. If your content is marked up correctly, then you will be able to use all sorts of transforms for publishing, including support for needs that might only evolve a year or more down the road. Correct use of DITA elements, is key for supporting single-source to multiple channels and platforms. Taking the extra few moments up front to learn about how to implement the DITA elements makes writing faster, maintenance faster and opens up future publishing opportunities.

Up front in your DITA project, the emphasis should be on correct use of DITA elements (”semantic markup”). Choosing the DITA elements that reflect the structure of the content.

Comments Off

How Does Markup Mentoring Work?

Posted in DITA, Minimalism, Technical Documentation by katriel on the July 31st, 2013

How does the content audit process work? As writers prepare content:

  • the markup mentor – usually one of the DITA gurus at Method M – reviews and comments.
  • writers can also ask questions as they write and get direction/feedback.

The overarching goal is to develop and reinforce “best practices”, from the get go, for the vanguard team moving to DITA — with the anticipation that the best practices will be incorporated in formal style/tagging guidelines, but even more importantly will become a part of the writing culture in your organization.

Comments Off

Therapy moves online (not DITA, but very cool)

Posted in dentist web site, health care web sites, online therapy by katriel on the February 12th, 2013
I promise to get back to DITA content auditing soon, but I just need to share with you a new site launched by our Therapy Everywhere division. Transitions Counseling, based in Dallas and Plano, provides face to face and online counseling for students moving into adult life, and for older adults transitioning into retirement.

Did you know that some dentists offer mercury free practices? That laser dentistry can make some dental procedures pain-free? If you need dental care in Brooklyn, you might want to check out Dr. Steve Eisenberg’s dental practice in Sheepshead Bay, recently launched by our GoMDweb division, with online solutions for dentists and physicians,

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.
Yours
! Katriel

Next Page »