Technically Speaking

When you are writing content in Flare, you may decide that you want to re-use some content that you previously added to another topic.

We’ve discussed before how the best way to do this is to use a snippet, which essentially is a really long, formatted variable.

To do this in Flare, you create a new snippet, then you locate the text you want to re-use, and copy the text out of that topic and paste it into the snippet. Then you replace the text in the original topic with the snippet, then insert the snippet into the new location.

This isn’t too hard, but I’ve long wanted to use a nifty shortcut, but couldn’t figure out how to make it work. See, when you are writing in the XML editor, there is an option on the context menu (right-click) menu that allows you to create a snippet from an existing block. That works great if all you want to add to the snippet is a single paragraph, but it doesn’t work if you want to add multiple block-level elements into the snippet.

Today I thought of a way to do this quickly and easily, even with multiple blocks.

Here is what you do.

1. Open the topic that contains the text that you want to turn into a snippet.
2. Select the blocks that you want to re-use.
3. From the Format menu, select Group.
4. From the pop-up, select the div option. (This groups the selected content into a single block, the DIV block.)
5. Now, right click on the DIV block, and select “Create Snippet”.
6. Give the snippet a name and click the Create button. The snippet is created and inserted into the original topic
7. Go to your new topic and insert the snippet into it.

If you are creating Word or Framemaker output, you may need to change one additional thing:

1. Right click on the snippet block, and select “Open Link”. The snippet file itself opens.
2. Right click on the div block, and from the Edit menu, select “Unbind”.

This removes the div, which can cause positioning problems in Word and Framemaker outputs. (I don’t actually know if you NEED to do this extra step, but it isn’t a bad idea.)

Using a div to create a snippet is much faster, in my opinion, when you are trying to create a snippet from a multi-block selection. Try it, and I think you’ll agree.

—–

(This article has been cross-posted on DocGuy Training.)

MadCap Software today released a publicly-available beta version of Blaze, their new single-sourcing tool for creating print documentation.

If you’ve been following the industry buzz lately, you’ve probably heard about Blaze. Now you have a chance to look at a beta release of Blaze version 1.

To sign up for the beta, first check out the info on Blaze from MadCap’s website. Then go here to sign up for the beta. Fill out the form, and MadCap will contact you with information on participating in the beta.

I’m downloading my copy right now. I’ll let you know how it goes.

So it’s been a while since I posted much on Flare. For a while I wasn’t using Flare in my daily work flow; I’ve actually moved all new development on the four product lines I support into my Flare work flow, but we keep needing to go back and do dot releases on an older version of our software. When I thought it was only going to be one dot release, it didn’t seem prudent to move the source into Flare. Now we’re working on the FIFTH dot release. Seems I should have made the switch. Oh well.

Anyway, for about a month now I’ve been back using Flare full-time again, and I’ve really been enjoying some of the features in the 3.x line. I didn’t really delve much into them when 3.0 first came out, so many of the new 3.0 features I’m only starting to use now in 3.1.

In any case, here are my favorites so far:

Running Headers/Footers in Word Output

One of my big complaints about InDesign compared to FrameMaker was that InDesign didn’t have an elegant way of allowing running headers and footers in your printed output. A running header/footer means the header/footer’s content changes to reflect the section of the documentation you are in. So a running header might automatically contain the name of the chapter, and a running footer might contain the text of the most recent H1 or H2 style in the document. This makes the printed document much more accessible, easy to read, and professional.

Flare 3.1 gives you the option to use running headers and footers on your Printed Masterpages. You add a variable set to your Flare project that defines the heading styles you want to grab as the header/footer text, then you insert those variables into your Masterpages.

The result is exactly what I asked for. Then I found out, I didn’t know what I wanted.

See, the running headers/footers work great if you stick to a rigid format (a-ha! the structured authoring debate comes again!) in your document structure (e.g. H1 style for chapter title; H2 style for section heading, etc.). I thought I had done that. When I created my printed output, I realized that I have certain sections in my Flare WebHelp that I have as drop-down heads. The style of the drop-down heading matches my H2 style, so in the printed output, you can’t tell whether the WebHelp uses an H2 or used a drop-down head.

That works great for masking the non-standard structure, but Flare can either use the most recent H2 in the footer, or it can use the most recent drop-down head in the footer. I have to go back to my documents and re-structure them so they are all structured the same in order to use running headers and footers in my printed output.

I don’t blame Flare for that, though. I need to pick a structure and stick with it. It’s not Flare’s fault I’m using two different structure formats in different topics.

I give the running headers/footers in Word feature two thumbs up. Thanks MadCap!

Source Control Integration from within Flare

A new feature in Flare 3.0 was source control integration from within the Flare interface. This is a cool feature that I didn’t know I needed, but one that I like the more I use it.

Flare provides direct integration with Microsoft Visual Source Save and Microsoft Team Foundation Server, and provided third-party integration with other source control systems that use the MS SCC API interface. My documentation is stored in an SVN repository, so I had to purchase a third-party plugin to get Flare to work with my source control system. (I bought my plugin from PushOK software, a vendor out of Russia. It cost me 600 Russian Rubles, which came out to about 25 dollars. I’ve been using the plugin now for a couple of months, and it works fine for me.)

I have only a few complaints here: I wish Flare supported the most common formats natively, so I didn’t have to purchase the plugin separately. And I don’t love how for some actions (like moving a folder of topics to a different location in the tree) it seems that either Flare or the plugin checks in each change as a separate revision in the source control. (I suspect this is the plugin’s doing.) Also, I purchased the plugin for one computer I use for editing the project (my main computer) but I didn’t purchase it for my backup computer. When I edit the project using my backup computer, I have problems because the SVN connection settings are stored in my flare project file, so the project files on my two computers can’t match. I hate having to purchase an extra plugin just for the occasional use of the backup computer, so I’ll probably just ignore the inconsistent settings in my project files.

Basic Style Editor

One of Flare’s strengths is the CSS editor included in Flare. In the 3.x line, they’ve stepped things up a notch by including a basic style editor and an advanced style editor. (The advanced style editor is basically the same editor we’ve seen in previous versions of Flare. The basic style editor is a new concept in 3.x.)

The advanced style editor shows all the inherited and local styles and classes in the style sheet. It also shows all the properties available for the styles and classes and lets you change them. You have quite a bit of control over how much information is shown on the screen; You can limit the styles by group, and you can limit the properties list by grouping by type, showing only set properties, or even a smart list of “relevant” properties–properties Flare thinks you might want to change for that style.

Two areas for possible improvement are: (1) Flare still has a habit of modifying my CSS just because I opened it. Example: for some reason it doesn’t like the asterisk symbol in complex selectors (e.g. ul * ol), and any time I open my stylesheet in Flare, it replaces all my asterisks with a “\00002A” which I guess is code for asterisk or something. (2) There is a toggle button to switch between the advanced view and the simplified view. However, the toggle button text shows you the view you will see if you click that button. So, in the screen shot included here, you’ll see that the toggle button says “Simplified View” even though you are seeing the Advanced View. It’s not a big deal, but it makes for a slightly confusing interface. Not to mention that the Flare help system has to explain every time how to check to see if you are really viewing the advanced view or the simplified view. Simply putting the word “Show” in front of the text would really have made this easier.

Conclusion

I still love Flare. There is a learning curve to get up and running with it, but it is a very powerful tool that in my opinion just keeps getting better and better.

——-

PS: I suppose I ought to post a bit of news (and a sort-of disclaimer). Due to my activity in the Flare user forums, last month I was invited by Flare Support to be a MadCap MVP, and I accepted. I use the pseudonym “DocGuy” in the forums. This doesn’t make me a MadCap lackey; some MVPs are known for speaking their minds in opposition of perceived problems at MadCap. However, I am a volunteer forum moderator for the MadCap Forums, and I am a MadCap aficionado. But I don’t suppose that last bit is very surprising to anybody.

This is the second in a series of posts on structured authoring.

In the previous post, I discussed the definition and benefits of structured authoring.

A quick reminder: structured authoring is means separating content from its format, and designing your document in a way that you
can easily add/change format to any particular part of your document. Think of it as filling out a form.

I had planned to start talking about tools right away, but I thought it would be important to first give a concrete example of a structured document. Regardless of the tool you choose to use, the process of creating a structured document is the same. Before you even open a software tool, you have to sit down and determine what content you want in your document, and figure out what structure that document has, either inherently, or can be applied to it.

Examples are best here, so let’s take a specific type of document and look at the inherent structure that exists. We’ll use a resume as an example.

Regardless of how you format a resume, it is comprised of a couple of things: your name, your contact information, and various sections that pertain to your jobs, education or experience.

With a structured writing approach, we will call each of these items “elements.” Some elements, such as name, only appear once in a particular document. Other elements, such as section will occur multiple times.

Here are some basic rules about a resume:

• There is a name element. It can occur only once.
• There is a contact information element. It can occur only once.
• There is a section element. It can occur as many times as needed.
• Sections are comprised of what we’ll call “experience” elements. An “experience” in the Education section would be a particular school you attended. An “experience” in the Work Experience section would be a particular job. Each section may include multiple experience elements.
• An experience element is comprised of a title, location, start date, end date, and a description.

Here is an example:

Name: Barrie Jones
Contact Information: 456 Anystreet, Moscow, Idaho, 208-800-9000

Section: Work Experience
 Experience: ACME Corporation
  Title: Summer Intern
  Location: London
  Start Date: June 2008
  End Date: August 2008
  Description: Office secretarial work including preparing and distributing meeting minutes, filing, and document editing.
 Experience: ABC Publishing
  Title: Editor
  Location: New York
  Start Date: September 2007
  End Date: June 2008
  Description: Edited manuscripts of to-be published books.

Section: Education
  Experience: Johnsontown University
  Title: BA in English
  Location: Johnsontown, Idaho
  Start Date: September 2002
  End Date: May 2007
  Description: Graduated summa cum laude; National Honor Society member; Dean's list for four semesters running


Now you’d probably never turn in a resume to a potential employer in the format above, but by doing this exercise, you’ve been able to identify the content in your resume that is similar to all other items in your resume. You’ve separated the structure from the formatting.

You should note that I used generic terms for all my elements. I used the general “section” in place of “education” or “work history”. I used the general “experience” instead of “school name” or “employer name”. I did this intentionally, because it allows me to re-use the section in a different way, while applying the formatting to only one element. When it comes time to format, all my educational institutions will match my jobs, in terms of formatting, which will give me a nice, balanced resume.

Once you have a structure in mind, you can figure out what other sections you want in your resume, and you can see if you need additional elements to represent that content, or if the elements you’ve defined are sufficient.

For your resume, you may want to have a section on software tools. This section might fit in this structure:


 Section: Software Tools
  Item: MS Office 2007
  Item: OpenOffice
  Item: MadCap Flare
  Item: Adobe Photoshop CS2
  Item: Adobe InDesign CS2

 Section: Awards
  Item: Rhodes Scholar 2002
  Item: Eagle Scout 2000

 Section: References
  Reference: George Bush
   Reference Address: 1600 Pennsylvania Ave, Washington DC
   Reference e-mail: president@whitehouse.gov
  Reference: Albert Einstein
   Reference Address: 1234 Big Bang Ave, Cosmos
   Reference e-mail: albert@theoryofrelativity.net


Notice again how I used the generic element “item” instead of “tool” or “award”. Again, that allows me to reuse the element and apply the same styling.

I have pieces of my References section, however, that don’t match any other elements in the document, thus they get their own names so I can style them separately.

You should also note that when I pick an element name, I’m picking a description of the element, as opposed to the eventual formatting I want to place on the element. In essence, I’m describing the structure of the content. Remember, we are trying to separate the content from the formatting.

Once you’ve got a good structure in place, you are ready to pick an authoring tool. Future posts in this series will discuss various authoring tools, and show you how to apply formatting to the content using the features in that particular tool.

We’ll keep referring back to this resume example to show you how you can format this data using different authoring tools. Stay tuned!

Today I begin a series on structured authoring, a topic of particular interest to documentation professionals (and which you may find tedious, if documentation isn’t your thing; that’s okay).

We start off by asking the obvious question: What is structured authoring? I’m glad you asked.

Here is a definition from sct-sf.org: “Structured authoring is a method of writing and arranging content that relies on rules and automatic validation to enforce the rules. Structured authoring separates content from presentation; information is labeled according to its purpose. [...] This type of writing may restrict or constrain you at first, but it saves time in the end by forcing documentation to be complete, consistent, and designed for re-purposing. Writers spend time on content and are no longer permitted to apply formatting. [...] Benefits of structured authoring include improved document quality, improved author productivity, and enhanced content sharing and re-use.”

Take for example a Master’s thesis. A Master’s thesis has a pre-defined format that is rigid. There must be a title page, followed by an optional copyright page. There must be a table of contents, and an abstract, but the acknowledgments page is optional. There are five chapters to the document. The first chapter is the introduction to the thesis. The second chapter is the review of literature. The third chapter is the definition of the current study. Chapter four is the chapter where you discuss the results. Chapter five is the conclusion.

Within each chapter there are generally (up to) five levels of headings. Each heading can contain things like body text, bulleted lists, images, and tables.

In essence, you have a document that is adhering to a structure that you can predict before you even read it.

Structured authoring has a number of potential uses. It helps documents written by separate authors to maintain structural consistency. For example, I first encountered structured writing when I worked at the MTC. I was documenting second-language acquisition software, and I defined a very rigid document structure for the design documentation for the various activities available in the software. The documents all began with a heading that was the name of the activity. Next there was a screen-shot from the application showing that activity in use. There was a heading called Instructions. In this section there was text directed at the learner, giving them instructions on how to use the activity. The remaining sections had specific titles, with matching content.

In this case, you always knew which headings were going to be in the document in what order. You could predict the content within the headings. The document had a very rigid overall structure.

So, at the MTC structured authoring was great because it gave us a professional look and feel across every activity document. Regardless of the document’s author, the documents all followed the same predictable, professional pattern. Thus, structured authoring is one way to allow multiple authors to work on the same project while ensuring consistent output.

Another benefit from structured authoring is that it allows writers to us authoring tools to provide consistency across multiple documents with regards to formatting and design. Generally, a document that is structured uses a style sheet of some sort for formatting. In most programs, you can have an external style sheet that you can reference for your styles.

In the case of the thesis, you can just write using H1, H2, H3 tags, etc. When the time comes, you can format your H1 style to appear a certain way, and all corresponding H1 text changes to the new style. Make changes in one place, and all documents that link to that style sheet are automatically changed. And because you are enforcing structure on your documents, you know that the styles will work where you expect them to.

I’m sure you can see how when you are working in a large document, or in multiple documents how using structured styles allows you to make style changes much easier as the project evolves or as needs change.

If you are new to structured authoring, you are probably wondering how to start writing structured documents. In later posts in this series, I’ll explore how to write structured documents using a variety of tools out there. In those tool-specific posts, I’ll point out the strengths and weaknesses of each of the tools.

So that is your introduction to structured authoring. You maybe aren’t familiar with the term, but I’ll bet the concept isn’t totally foreign to you. Stay tuned to posts in this series to see how you can use structured writing techniques in your favorite software programs.