Why Should I Care About DITA?

DITA-sprout

Source: TechWhirl

DITA, Darwin Information Typing Architecture, is an XML-based standard that is used primarily for technical documentation and increasingly for other types of documentation too.

If you’re not applying DITA as your documentation standard, then you’re working much more slowly and inefficiently than you ought to.

DITA Saves Time

If you and your writers are forever mucking around with Word style, templates, footers and headers and generally wasting your time on not creating content, then you should seriously consider moving to DITA.

DITA separates content from formatting so that writers write; they don’t format. Formatting is applied automatically and consistently as part of the publishing process.

That extra time gained from authoring in DITA doesn’t mean that you can reduce the writer headcount, because the extra time should be spent focusing on writing the right information, the information the user really wants and needs…which leads to the next reason you should care about DITA: increased quality.

DITA Introduces Quality and Consistency

DITA gives writers a clear, repeatable, yet customizable model to write from. For example, DITA requires every topic must have a title; pre-requisite information for performing a task always precedes the context of a task (and the steps); and a task result always follows the steps.

With DITA, writers have (just) enough structure to consistently write according to best practices, like telling people what they need to have or know before telling them the first step. It’s not uncommon to find a step that surprises the reader with information they should have known before they even started the task. That sort of information is now clearly placed before the steps begin.

Writing using DITA leads to clear, consistent information. In fact, most writers take this one step further and start to identify real user goals and then write to those goals instead of writing based on features. This further increases the quality and usability of the content.

At the same time, formatting discrepancies disappear because formatting is applied centrally and programmatically at publishing time, rather than randomly throughout the content creation process.

DITA Increases Usability

DITA introduces a shift—from chapter- or book-based writing to topic-based writing, where each chunk of information is clear and complete on its own. Furthermore, each chunk, or topic, has a clear purpose. The core of DITA includes different topic types, each written to fulfill a specific users’ goal: concept to explain, task to instruct, reference to inform.

Separating content into discrete, highly usable but clear topics makes them more findable. Users can navigate right to the information they need, read just the pertinent information (because the rest is there, a click or swipe away), and then go about their day.

Happy users make really good customers and no one is happier than the user who finds exactly what they need in the documentation.

DITA Opens Up the Door to Publishing Options 

By having content in XML, you’re freed from the constraints of one particular output format, like HTML or PDF. You are limited only by your technical skills at transforming XML into any and all other outputs that you need (and that your users need).

From ePub to Excel or PDF to PowerPoint, creating the outputs you choose is a matter of mastering transform languages (or hiring someone who can create what you need using those transform languages). Your outputs are entirely configurable, looking and behaving exactly as needed.

It gets trickier when you try to integrate DITA outputs with other tools, like publishing through WordPress or Drupal. However, it’s usually a matter of time and money rather than an impossibility.

DITA Saves Money 

By not messing around with formatting and by having a clear standard to write and reuse content, writers can write faster. When content is in DITA, it becomes an object that can be used anywhere it’s needed. No more copy/paste. This means savings when you’re writing new content, updating existing content, or assembling new product documentation.

Translation also becomes a major source of savings in a DITA environment. Instead of translating complete documents over and over, you only need to translate the specific content that has changed. Organizations regularly see a savings of 50% or more when they translate DITA content rather than Word, FrameMaker, or InDesign.

Summary 

These are just the high-level advantages of DITA. We haven’t even touched on the ability to tailor content to a particular type of user, make content even more findable through faceted search, or make reviews faster and easier (and on time!).

If you care about the quality of your technical content, you should care about DITA, and start planning how to move your documentation to a new level.

Have something to add? Please share it in the comments.

 

The Punctuation Revolution

punctuation

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

What happened to punctuation as we knew it? If you’ve been striving to use it properly in print, digital technology has changed the way we use it today. For example, we are more focused on word count than sentence structure. Even for the non-grammatically obsessed, deviations from the established rules of punctuation and grammar indicate a break from tradition.

With the proliferation of smartphones, tablets, texts, and social networking, we’re communicating our thoughts so much and so fast that punctuation has become less important, almost superfluous. Internet culture generally favors a lighter, more informal style of punctuation.

Technology has led us to use written language more like speech, in a real-time, back-and-forth between two or more people. For example, a line break allows people to more accurately emulate in writing the rhythm of speech.

When texting first became popular, all grammar bets were off. It’s now the emotion or intent behind the communication that matters. For example, periods and commas have become unnecessary. As long as you get your point across, sentence structure has become a thing of the past. Following are some examples:

The period: Why use it at the end of a sentence when the meaning doesn’t change whether it’s there or not. It can be completely absent and becomes implied. Other times a comma takes its place.

The comma: Once it was used to separate phrases in a sentence, now (rather than a semicolon) it’s used to string together two sentences for one train of thought.

The semicolon: It’s not quite a comma or period. The semicolon was useful as a separator and connector, but today no one uses semicolons in day-to-day casual writing.

The exclamation point: Aside from eliminating punctuation, we also use it excessively. For example, adding five exclamation points instead of one shows that we are passionate. In the past, using exclamation points too frequently was thought to make them less meaningful.

As the long-established rules for grammar have faded, and we spend hours communicating by digital media, it seems punctuation has just been a fad, and it comes and goes with the times.

Have something to add? Please share it in the comments.

Five Tips for Writing a User Manual

Technical-Manuals

*Due to web issues, we lost information on who authored this piece.  If this is your work, please let us know and we will give you publishing credit.*

A successful user manual provides quick answers to questions that users might have about how to complete tasks. Technical writing focuses on the tasks along with the concepts that support them.

Here are five practical tips on writing user manuals.

Think like a user

You should have a good understanding of your users so you can understand the information they need to know, how they approach each task, and when they might use approaches to tasks that are unexpected.

Use active voice

Sentences that use active voice emphasize the user and are easy to read and understand. In active voice, the subject and verb in the sentence are clear. In passive voice, the subject is unknown and is acted upon by something that is not known or not stated. Passive voice uses verbs that include a form of “to be”.

Focus on the reader

When writing information that involves the reader, such as instructions, pull readers into the document by using “you” to make the content relevant to them.

Compare the two sentences below.

Reader focus: You can choose from one of three options for viewing content in the editor. 

Lack of reader focus: There are three options for viewing content in the editor.

The sentence that uses “you” makes it clear that the reader is the person doing the action.

Write clear instructions

The primary objective of user manuals is to help users complete tasks. Here are some guidelines.

  • Use numbered lists for instructions, unless the instruction includes a single step.
  • Use parallel construction for each step. Typically, you should start each step with an imperative word that provides clear cues.
  • Avoid using a system response as a step. For example, don’t say, “The Info dialog window opens” as a step. Mention the system response at the beginning of the following step (for example, “In the Info dialog window…”.
  • Provide just enough information so that the user can complete a task or understand a concept. Concise content makes it easier to understand concepts and tasks. 

Establish standards

When creating documentation, there will be areas where there may be more than one way to spell a word, refer to an object, caption graphics, punctuate sentences, lay out a page, and organize information. Establish standards by making decisions for users beforehand.

In addition, use an established style guide, such as The Chicago Manual of Style and Microsoft Manual of Style to establish some specific guidelines for your writing project.

Have something to add? Please share it in the comments.