Adopting Structured-and-DITA Best Practices, For Any Toolset

Copyright © Write Quick, Inc., 2016. All rights reserved.

Adopting Structured-and-DITA Best Practices, For Any ToolsetAdopting Structured-and-DITA Best Practices, For Any ToolsetMonique SempAugust 10, 2016

Introduction

About Riley and Monique

Presentation summary

□ All too often the “experts” imply that you must use some giant authoring/tools system with lots of overhead in order to get any of the benefits of structured/DITA writing. However, you can create well-structured, consistently-styled, and reusable content no matter what your toolset.

□ In this presentation, I’ll briefly cover the primary benefits of structured/DITA authoring and show how you can realize many of these benefits when using several unstructured tools (Adobe FrameMaker, Microsoft Word, and MadCapFlare).

□ Many references included, aggregated into a References section at the end.

Presentation will be posted to LinkedIn, www.linkedin.com/in/moniquesemp/.

August 10, 2016 2Adopting Structured-and-DITA Best Practices, For Any Toolset

Overview

This presentation is not a “how to not bother with DITA” or “how to replace DITA” talk, nor step-by-step instructions for using a given tool for any specific purpose. Rather, it’s a “things to consider, for a variety of benefits” talk. I’ll provide a lot of possibilities, some examples, and a list of references for learning more.

Outline (a large slide deck, but lots of it is simply reference material):

□ What is structured authoring, its features, and its toolset features?

□ Why isn’t everyone using DITA or DocBook?

□ Unstructured, Non-DITA? Adopt Its Features Anyway!

□ Unstructured Tools’ Support for Structure

□ Examples

□ Summary, Concluding Thoughts, References


What Is Structured Authoring?

There are many definitions (see References page), but at its most basic, it’s simply consistency in structure—the order of information for a given type of content—and consistency in writing.

Some tools, such as authoring suites for XML-based content, perform programmatic enforcement of the structure by DTDs (document type definitions) or similar mechanisms, such as Schematron and RELAX NG.

The most widely adopted standards-based frameworks for structured authoring are: DITA [http://dita.xml.org/] and DocBook [http://www.docbook.org/].

□ Problems: The Lightweight DITA committee struggles to define a functional subset of the 1,199-page DITA 1.3 spec. And for DocBook, the conventional wisdom is that you’ll discard the vast majority (>90%!) of the spec before creating content.

□ Goal becomes: Define a structure that suits your immediate needs and that’s extensible for future requirements.


Structured Authoring Features

To say that content is structured means (among other things) that it enables:

Easy content reuse—Content is referenced, not copied. Variables and conditions enable easy use of almost identical content.

Implicit focus on topic-based writing—The DITA specification defines topic types such as concept, task, and reference. The DITA standard uses a map to encapsulate all the desired topics; sort of like an outline.

Semantic styling—Adds meaning to the content, separate from the content itself. Instead of applying direct formatting to text, such as bold, the semantic tag itself defines the styling. For example, using a uicontrol tag makes it easy to change all instances from bold to italic.


Structured Toolset Features

Typical structured authoring tools, such as oXygen/XMetaL, Structured FrameMaker, and the DITA Open Toolkit, provide:

Multi-output publishing—Source files are used as input to a publishing engine. Like OOP (object-oriented publishing), the goal is WORM: Write Once, Read [Publish] Many.

Metadata support—Many uses: https://en.wikipedia.org/wiki/Metadata#Creation, and structured tools generally provide a GUI to easily manage metadata.

Portable content—Content can be round-tripped among different editors and publishing engines

Easy source control—Many structured tools integrate with popular source control systems. Because content is ASCII (except for image files), not binary, it’s easy to perform diffs and merges.


Outline

What is structured authoring, its features, and its toolset features?

Why isn’t everyone using DITA or DocBook?

Unstructured, Non-DITA? Adopt Its Features Anyway!

Structure

Examples

Summary, Concluding Thoughts, References


Why Isn’t Everyone Using DITA or DocBook?

If DITA, DocBook, and formal structured authoring tools are so great, why isn’t everyone using them?!

Lots of legacy content to convert or maintain.

Tools are expensive in terms of TCO (total cost of ownership). Some open-source tools are free to download but become costly to implement because of the technical skills required.

Steep learning curve.

Complex authoring-publishing ecosystem, which is difficult to manage for lone writers or small teams.

Long, or even infinite, ROI.

Depending on the content, DITA can be a solution that’s looking for a problem.


Outline




Unstructured Tools’ Support for Structure

Examples



Unstructured, Non-DITA? Adopt Its Features!

Writing is writing—You can define the content’s “structure,” write a good short description, and write in a topic-based fashion, even if you’re chiseling content onto a stone tablet.

□ Write topics—Adapt your “doc” for topics; write consistently via templates or model docs

□ Write a short description

Typical authoring tools provide many of the features that structured/DITA tools provide for creating consistent and extensible content:

□ Reuse content—Add variables and conditions for single-sourcing of almost identical content

□ Style things semantically

□ Standardize navigation aids (for example, automatic text for Prerequisites)

□ Add metadata

□ Publish to multiple channels

□ Version-control the content


Outline





Examples




By definition, a document’s structure is implemented within the context of the authoring environment’s (tool’s) fundamental strengths and weaknesses:

Adobe FrameMaker—Easier than Word with respect to creating style names and specifying behavior. But writers must still be diligent, and strong editorial review is required for enforcement.

Microsoft Word—Templates can be built with a specific set of styles that guide the writer (although some mechanisms “require” the use of Word’s internal style names). But, writers must be diligent when using the templates, and compliance requires a lot of editorial review.

MadCap Flare—Designed as a topics-based authoring tool, based on standards-friendly XHTML and CSS. Great support for templates, variables, and snippets, which makes content reuse easier than with other tools. Styling and structure still require strong editorial supervision.

Dev-Doc tools—(Not covered further in this presentation) Tools such as Javadoc/Doxygen, LaTeX, Markdown, and code-oriented text editors (Notepad++, SublimeText) also have mechanisms that let you adopt some things about structure, reuse, and syntax.


Caveats and Notes

Structure isn’t an all or nothing thing—You can choose to adopt the easiest things, the most important things, or some other category that fits your needs and ROI.

Another reason to adopt these concepts is to prepare for a new toolset/ecosystem and migrating existing content—Migrations typically require some of these changes or go much more smoothly if they’re implemented.

Some of these adaptations are short-term solutions/workarounds—As such, they can be great quality/productivity aids, but do not take the place of the ideal—tools chosen as a result of a docs/needs analysis.

Not all features are in all a tool’s versions—I’ve indicated the versions of the tools used in the examples. I’m using recent or the latest versions, and I believe that the features I’ll be showing have been in these tools for a number of versions. But if you’re evaluating or using a different version, YMMV.


Outline





Examples



Examples

1. Create structure—Write topics (not books or chapters); design and adhere to consistency across topics.

2. Write a short description.

3. Reuse content—Whole topics, fragments, and slightly-different content.

4. Style content semantically.

5. Standardize navigation aids.

6. Add metadata.

7. Publish to multiple channels—PDF and non-PDF.

8. Version-control the content.


1a. Write Topics: “Doc” Structure

In DITA, topic-based authoring is designed in. Separate files for every topic are included in a ditamap, and DITA-aware editors enforce structure as content is created. Hierarchy is typically flat (few heading levels). Some non-structured tools easily support separate files for every topic, while others require using advanced features.


Frame (2015) Word (2010) Flare (11)

For each “chapter,” add a folder to the .book file. The folders serve as containers for separate (topic) .fm files. See http://blogs.adobe.com/techcomm/2014/07/why-upgrade-from-fm7-8-or-9-5-book-building-and-external-references.html

A couple of approaches:

• Create separate files for every topic, and include them in a master doc. Historically, master docs have had problems, but they do seem workable.

• DitaExchange integrates with Word, letting you create DITA topics and maps without knowledge of DITA markup.

See References page.

• Based on XHTML, whose specification defines a well-formed document—a document that adheres to the syntax rules specified by the XML 1.0 specification. So structure is inherent in the content. See References page.

• Fully and easily supports separate files for topics, which can be included in any number of docs (books, help systems, etc.).

1b. Write Topics: Consistently Styled

In DITA, standard topic types are concept, task, and reference. With specialization, you can create custom topic types, such as Troubleshooting. DITA-aware editors enforce the structure of the content by validating it (its element tags) against the DTD.

With non-structured tools, you can create templates and model docs, develop file naming conventions, and use paragraph style attributes to ensure consistently structured content. These manual mechanisms do require diligence and editorial review.

Implementation-By-Tool:



• Use file naming conventions.

• Use model template .fmfiles.

• Configure Next Pgf Tag for all paragraph styles.

• Use file naming conventions.

• Use model template.dotx/.dotm files.

• Configure Next Pgf Tag for all paragraph styles.

• Create topic templates that contain predefined CSS classes, in a given order.

• Use a metatag to define the topic type.

• Some Flare styles contain logic for the next line’s style; all styles are editable via CSS.

Create Topic Template: Flare

1. (Not illustrated) Use the Flare XML Editor to create a new topic file, structure it as desired, and save it to the Flare Template Library folder.

2. From the ribbon’s Tools tab, click Manage Templates to open the Templates Manager for project template linking.

3. When you create a new topic, select the desired topic-template as the New from template source.

Flare Master Projects ensure that a team of authors always has the current templates.


2

3

Examples






6. Add metadata.




2. Write a Short Description, <shortdesc>

DITA has the <shortdesc> element, whose importance cannot be overstated.

□ See “Guidelines for Writing Effective Short Descriptions”, in the DITA Best Practices book.

□ Also see the OASIS White Paper, DITA Feature Article: Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descriptions (18 March 2016), https://www.oasis-open.org/committees/download.php/57803/DITA-Adoption_2016_Writing-Effective-Short-Descriptions.pdf




Create a shortdesc paragraph style, and assign this style as the Next Para for all heading styles.

Create a shortdesc paragraph style, and assign this style as the Next Para for all heading styles.

Create a CSS class that identifies a specific variant of an XHTML element.

The <shortdesc> Element: FrameMaker

To create a <shortdesc> “element” and configure FrameMaker to automatically “use the structure”:

1. Using the Paragraph Designer, create a shortdesc paragraph tag, and set its Next Pgf Tag to the “regular” paragraph, such as body.

2. For all heading styles, set their Next Pgf Tag to the shortdesc paragraph style.

When you press Enter after typing a heading, the next paragraph is the shortdesc, followed by body.


1

2

The <shortdesc> Element: Word

To create a <shortdesc> “element” and configure Word to “add it to the doc”:

1. Create a new paragraph style, shortdesc, base it on the “regular” paragraph, such as body, and assign its Style for following paragraph as body.

2. For all heading styles, set their Style for following paragraph to the shortdesc paragraph style.

When you press Enter after typing a heading, the next paragraph is the shortdesc, followed by body.


1

2

The <shortdesc> Element: Flare

Neither XHMTL nor CSS define a shortdesc element; so create a CSS class:

1. Type a semantic element’s prose into a <P> element.

2. Create a custom CSS class (right-click the class in the structure bar, select Style Class > Create Style Class), p.shortdesc, and apply it to the prose.

Requires manual application; CSS does not support structured behaviors such as next paragraph or prev paragraph.


1

2

Examples






6. Add metadata.




3a. Reuse Content: Whole Topics

In DITA, any topic can be included in any number of ditamaps (doc containers). Typically you use a CCMS (content configuration management system) to keep track of topic use.

Non-structured tools provide some capability, but you’ll need to manually keep track of things or use 3rd party tools.




• Write the topic in a standalone .fm file, and import it as a text inset.

• Recent thread from the [Framers] list: Using Frame as a little CMS, http://www.mail-archive.com/framers%40lists.frameusers.com/msg65018.html

• Master documents.

• SmartDocs is designed with content reuse in mind; see http://www.thirtysix.net/

• RiverFloe is a "document generation machine for Microsoft Word." See http://www.riverfloe.com/

• Topics can be included in any number of projects.

• Included snippets are automatically updated if you update the source.

3b. Reuse Content: Fragments

In DITA, <conref> and <conkeyref> elements act as variables that you can include in any topic, as well as customize on a per-document basis.

Non-structured tools typically provide this capability via variables.




• Customize system variables.

• Add user variables.

• Easily manage variables via tools such as LeximationBookVars, http://leximation.com/tools/info/bookvars.php

• Use AutoText to define content fragments. Use the AutoText field code to enable easy doc updates for modified AutoText entries.

• Custom variables (in Advanced Properties) let you create true variables.

• Building blocks provide even more control.

• See References for details.

• Variables can be used in topics, snippets, and print page layouts.

• You can define variable sets.

• You can define a set of doc-specific variables (title, version, etc.), and assign them as UPDATE-IN-TARGET. For each target, specify the variable values.

3c. Reuse Content: But Change it Just a Little

In DITA, conditions let you manage small output variations in a topic, making it easy to maintain consistency; for example, a task that’s virtually the same for two different product’s docs. Some non-structured tools provide advanced condition management, while others require extensive workarounds.



• Full-featured conditional text management provided.

• Best practice: Create a per-project .fm template that has only conditions. Import its Conditional Text Settingsinto all a doc’s .fm files.

• No dedicated function, but by using hidden text, you can fake it; see References.

• Use SmartDocs’ conditional functionality, http://www.thirtysix.net/smartdocs/features.

• Use Document Automationin Clio, a cloud-based management software system for the legal industry; see References.

Conditional text feature lets you tag content at the:

• Topic-file level

• ToC level

• Target level

• In-topic content level

• In snippets

Examples






6. Add metadata.




4. Style Content Semantically

Although it’s possible to apply hard-coded formats to DITA content, the temptation to do so is reduced by the typical non-WYSIWYG editorial view. Typically, formatting is applied at publication time, based on the content’s applied elements, according to style sheets and tool-specific mechanisms.

For non-structured tools, best practice is still to eschew hard-code formats such as bold and italic. Instead, create meaningful character and paragraph styles to apply to the content. For example, create a cite character style instead of using Ctrl-i to apply italic.




Create character and paragraph styles; for example:

• cite• uicontrol• code• filepath

Create character and paragraph styles; for example:

• <cite>• <uicontrol>• <code>• <filepath>

Create a CSS class that identifies a specific variant of an XHTML element. For example: a div element, which in turn can specify unique formatting to its child elements.

Semantic Tagging: FrameMaker

Create semantic char styles instead of using formatting. For example, for doc titles, use a cite char style instead of applying italic formatting:

1. Using the Character Designer, create a cite character tag, assign the Angle as Italic, and assign all other attributes As Is.

2. After you type the doc title, select its text, press F8 (the shortcut for Apply Character Tag), and type/select cite.

Now it’s easy to revise the format of all citations, or to search for all of them.


1

2

Semantic Tagging: Word


Create semantic char styles instead of using formatting. For example, for doc titles, use a < cite > char style instead of applying italic formatting:

1. Create a new character style, < cite >, assign its Style based on as (underlying properties), and select italic.

2. After you type the doc title, select its text, press ctrl-shift-s (the shortcut for Apply Styles), and type/select < cite >.

Now it’s easy to revise the format of all citations, or to search for all of them.

1

2

Semantic Tagging: Flare

Neither XHTML nor CSS define semantic tagging except coincidentally (such as cite and code).

1. To mimic semantic tagging, apply a CSS class to a design element, DIV, or SPAN.

Now it’s easy to revise the format of all instances of a given class, or to search for all instances.

Note: Flare does not have a mechanism for enforcing a given sequence of CSS classes. Editorial oversight is required.


1

Examples






6. Add metadata.




5. Standardize Navigation Aids

Typical DITA output transforms add standard navigational text based on element types; for example, “Prerequisites” before a <prereq> element, and “What to do next” before a <postreq> element.

When using non-structured tools, you can style the paragraphs to automatically include standard lead-in text. This way, you don’t need to enter it, and global changes are easy.




Create paragraph styles such as prereq and postreq. In the Paragraph Designer:

• Use the Autonumber Format to specify the lead-in text, such as “Prerequisites” and “What to do next”.

• Assign the Next Pgf Tag to a bullet style paragraph.

Create paragraph styles such as prereq and postreq. Use outline numbering to specify the lead-in text, such as “Prerequisites” and “What to do next”.

(For help creating numbered styles that display lead-in text instead of numbers, see the References page.)

Flare has built-in features for creating browse sequences, related topics, and more.

Examples






6. Add metadata.




6. Add Metadata

In DITA, you can create <metadata> elements, with a variety of attributes, and apply the metadata to maps and topics in a very granular fashion.

Unstructured, “real” authoring tools (vs. simple text editors) also include features for defining metadata.




• Supports Extensible Metadata Platform (XMP).

• Use the File Info feature for book and/or file metadata.

• For historical info, see http://www.iptc.org/std/Iptc4xmpCore/1.0/documentation/Iptc4xmpCore_1.0-doc-CpanelsUserGuide_13.pdf.

• Add the Prepare Documentfunction to the ribbon (see References), and configure the (Document) Properties.

• To add additional metadata (or for variable use), access Document Properties > Advanced Properties > Custom tab.

Includes a variety of built-in metadata controls:

• Topic types

• Custom file tags

• Any XHTML-compliant tagging structure that you want to create.

Metadata: FrameMaker

FrameMaker supports the Extensible Metadata Platform (XMP).

To set the metadata at the book level:

1. In the book panel, right-click the book file and select File Info.

2. Enter the information for the metadata fields and click Set.

Generally when you Save or Publish the FrameMaker book, the File Info is automatically propagated to the output.


1

2

Metadata: Word

To enable metadata management, add the Prepare Document function to the ribbon (see References). Then add metadata:

1. (a) From the ribbon’s Prepare tab, click Prepare > Properties. (b) Click the Document Properties list and select Advanced Properties.

2. In the Summary tab, enter the metadata, and click OK.

Depending on your publishing workflow, the metadata can be automatically propagated to the output.


1a

2

1b

Metadata: Flare (GUI Tools)

Flare provides a variety of Flare-specific metadata constructs.

Use a topic’s Topic Properties (figure 1) to specify a topic style class (topic type) and to add a description (freeform text).

Use File Tags (figure 2) to assign one or more attributes to topics.


1

2

Metadata: Flare (XHTML Editor)

Flare lets you add XHTML meta elements to identify and assign structured metadata (HTML <meta> tags) to a document: author, expiration date, key words, and so on.

Use a text editor (ideally one that recognizes XHTML structure) to manually add metadata to a Flare topic XHTML file.

Flare includes all metadata in online targets, which enables it to manage project content and to add metadata and other tagging to online outputs.


Examples






6. Add metadata.




7a. Publish to Multiple Channels: PDF

With DITA content, it’s difficult to get a PDF that is as polished and precise as you can with traditional tools such as FrameMaker. You must extensively customize stylesheets for use with your PDF transformation engine—typically the Apache™ FOP (Formatting Objects Processor)—which requires knowledge of XSL formatting objects (XSL-FO). Commercial tools such as Antenna House Formatter and WebWorks ePublisher help a lot, but the work is still extensive.

Unstructured tools generally let you easily control the design of your PDF output.




Polished, highly-customized output is “easy.” You need:

• Good visual design(er).

• Good templates.

• Disciplined style use.

Polished, highly-customized output is “easy.” You need:

• Good visual design(er).

• Good templates.

• Disciplined style use.

• Professional PDF creator (Acrobat or Nuance).

Good-quality PDF is easy out-of-the-box. Not excellent because:

• Flare PDF engine does not recognize every CSS element or attribute; for example, CSS text-overflow, white-space, and overflow attributes.

• Flare can't process PostScript fonts.

7b. Publish to Multi Channels: Non-PDF

With DITA content, output for dynamic (responsive) HTML, CHM, EPUB, and othernon-PDF formats is excellent, with many good transforms—templates for transforming the DITA source content to the desired output—freely available from the DITA Open Toolkit.

Unstructured tools vary in their support for non-PDF outputs.




The File > Publish feature lets you create Responsive HTML 5, Mobile App, WebHelp, EPUB, Kindle, and more. You can configure many aspects of the transformation:

• Style mapping from FrameMaker styles (para, char, etc.) to CSS classes.

• Topic split/merge settings.

• Word has a Save As Web Page function, but it’s widely derided.

• Best approach is a 3rd party solution such as WebWorksePublisher, http://www.webworks.com/, to enable single-sourcing for multiple outputs.

• Easy to produce a variety of online, print outputs, and even Microsoft Word (which can be helpful to collect review comments).

• Supports CSS @media statements, which let you assert different CSS values based on media type or display type. See References.

Examples






6. Add metadata.




8. Version-Control the Content

DITA files are XML files, which are simply ASCII files, just like software code. As such, DITA content can be version-controlled just as software code is. Additionally, DITA authoring tools typically include integrations for one or more version control systems (VCSs); for example, oXygen integrates seamlessly with SubVersioN.

For non-structured tools, version control is affected by the doc content type. Some tools (Frame and Word) create binary files, which VCSs cannot diff or merge. Other tools (Flare) create UTF-8 files, but diff and merge can still be problematic.




• Binary file.

• You can save .fm files as .txt (use ExtendScript to automate) to facilitate diffs of the text.

• Includes integrations for Documentum, SharePoint, and DITA Exchange.

• Binary file.

• You can save .docx files as .txt to facilitate diffs of the text.

• See http://blog.martinfenner.org/2014/08/25/using-microsoft-word-with-git/

• Built-in support for many VCSs, including Git and Apache™ Subversion®.

• Care must be taken when merging files because Flare is VERY finicky about the structure and form of topic XHTML and CSS.

Outline





Examples



Summary: Tools† Support‡ for Features

†May require 3rd party tool integration‡As detailed in this presentation


Feature Frame (2015) Word (2010) Flare (11)

Topic-based structure

Consistent topic structure

<shortdesc> mimic

Content reuse: whole topics

Content reuse: fragments

Content reuse: slight diffs

Semantic styling

Para-styled navigation aids

Metadata

Multi-channel publishing

Version control

Concluding Thoughts

Full-on structured writing is based on useful principles, but in its purest form is technically demanding. However, you can borrow useful bits from structured authoring to the extent that your existing tools and workflows support it.

No matter your tool—whether you get to choose or it’s imposed upon you—look to the tool’s advanced features and integrations with other tools to let you adopt some structured/DITA best practices.

When you adopt structured authoring mechanisms for non-structured tools, recognize that the tradeoff for a less technically demanding approach is the necessity for more editorial review.


References (1 of 6)

Some links are previously mentioned in the presentation. All links valid at presentation time.

Structured Authoring

□ Topic-based authoring: https://en.wikipedia.org/wiki/Topic-based_authoring

□ Importance of short descriptions, an OASIS White Paper, DITA Feature Article: Short Descriptions Shouldn't Be a Tall Order: Writing Effective Short Descriptions (18 March 2016): https://www.oasis-open.org/committees/download.php/57803/DITA-Adoption_2016_Writing-Effective-Short-Descriptions.pdf

□ DITA Best Practices, A Roadmap for Writing, Editing, and Architecting in DITA; by Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt, © 2012

Metadata

□ Uses for metadata: https://en.wikipedia.org/wiki/Metadata#Creation

□ Historical information about the Extensible Metadata Platform (XMP): http://www.iptc.org/std/Iptc4xmpCore/1.0/documentation/Iptc4xmpCore_1.0-doc-CpanelsUserGuide_13.pdf


References (2 of 6)

Standards and Specifications

□ DocBook: http://www.docbook.org/

□ DITA: http://dita.xml.org/

□ S1000D: http://www.s1000d.net/

□ XHTML, CSS specifications: https://www.w3.org/

□ DTD: https://en.wikipedia.org/wiki/Document_type_definition

□ RELAX NG schema language for XML: https://en.wikipedia.org/wiki/RELAX_NG

□ Schematron rule-based validation language: https://en.wikipedia.org/wiki/Schematron


References (3 of 6)

Tools

□ oXygen XML Editor: https://www.oxygenxml.com/

□ DITA Open Toolkit: http://www.dita-ot.org/

□ WebWorks ePublisher: http://www.webworks.com

FrameMaker-Related Links

□ Using folders as containers for topics: http://blogs.adobe.com/techcomm/2014/07/why-upgrade-from-fm7-8-or-9-5-book-building-and-external-references.html

□ Using Frame as a little CMS: http://www.mail-archive.com/[email protected]/msg65018.html

□ BookVars plugin to manage variables: http://leximation.com/tools/info/bookvars.php

□ FrameUsers.com website and email group: http://www.frameusers.com/community/


References (4 of 6)

Microsoft Word-Related Links:

□ MS Word Helpers group on LinkedIn: https://www.linkedin.com/groups/1851284/

□ Word Master Documents: http://www.addbalance.com/word/masterdocuments.htm, http://techwhirl.com/wp-content/uploads/2010/09/Microsoft-Word-masterdocs.pdf, http://word.mvps.org/FAQs/general/whymasterdocscorrupt.htm

□ DitaExchange, which integrates with Microsoft Word: http://ditaexchange.com/; and a mention of DitaExchange by Scott Abel, the Content Wrangler, http://thecontentwrangler.com/2011/06/01/yes-you-can-do-dita-with-microsoft-office-and-sharepoint/

□ Tips for using AutoText in Microsoft Word 2010: http://www.groovypost.com/howto/microsoft/how-to-guide-for-using-autotext-quick-parts-in-office-2010/

□ Detailed information about Microsoft Word Building Blocks: http://gregmaxey.mvps.org/word_tip_pages/building_blocks_autotext.html


References (5 of 6)

Microsoft Word-Related Links, continued:

□ How to fake conditional text in Microsoft Word: http://www.technicalcommunicationcenter.com/2013/12/05/how-to-use-ms-words-hide-text-function-to-create-conditional-text-in-word/

□ SmartDocs, which provides single-sourcing, variables, conditional text features, and more for Microsoft Word: http://www.thirtysix.net/, http://www.thirtysix.net/smartdocs/features

□ RiverFloe, a “document generation machine for Microsoft Word”: http://www.riverfloe.com

□ Clio, which provides doc solutions for Microsoft Word, for the legal industry: Using Conditional Text in Document Automation, https://support.goclio.com/hc/en-us/articles/204459577-Tutorial-Using-Conditional-Text-in-Document-Automation

□ Details about creating paragraphs with automatic lead-in text: http://www.shaunakelly.com/word/numbering/numbering20072010.html; look for “Now we tell Word about the numbering itself for Level 1”.


References (6 of 6)

Microsoft Word-Related Links, continued:

□ How to add the Prepare Document functions to the ribbon: http://www.addictivetips.com/microsoft-office/prepare-word-2010-document-for-distribution-prepare-menu/

□ Blog post about using Git for Word docs: http://blog.martinfenner.org/2014/08/25/using-microsoft-word-with-git/ (this link is not resolving at the moment, but perhaps it will return)

Flare-Related Links

□ Well-formed document in XHTML: https://en.wikipedia.org/wiki/Well-formed_document, http://docstore.mik.ua/orelly/web2/wdesign/ch31_04.htm

□ Using CSS @media statements: https://css-tricks.com/snippets/css/media-queries-for-standard-devices/

□ UTF-8 format, used by Flare: http://microformats.org/wiki/using-utf-8

□ Users of MadCap Flare group on LinkedIn: https://www.linkedin.com/groups/86373


I encourage you to share these ideas (and slides)with your colleagues—the more people adoptbest practices, the easier writing becomes!

Any questions?

Tell us how it goes:

Monique Semp: [email protected], www.writequickinc.com, www.linkedin.com/in/moniquesemp/, 707-769-9541

Riley VanDyke: [email protected], https://www.linkedin.com/in/writingsolutions, 415.671.9584

Wrap-Up and Q&A


Technology

Adopting Structured-and-DITA Best Practices, For Any Toolset