Preparing FrameMaker source files
As we tested stationery settings and converting source files, we quickly realised that a lot of modification would be required before our source files would be ready for the wiki. Most changes were implemented because current practices simply didn't work in a wiki context, but others were necessary because of inconsistencies in how we authored in FrameMaker. Although this process was long and at times painful, it led us to formulate better practices which we might not have done otherwise.
The following are some of the modifications we made before publishing content to Confluence:
Make typographical changes
Issue: In procedures, we used arrows as separators. The arrows do not display correctly in wiki content.
Fix: We replaced all arrows with the ‘greater than’ symbol.
Issue: We used ampersands in Heading1s. But in our project, we set both Heading1 and Heading2 to Page break priority=1. As a result, page titles were inconsistent, using both “and” and ampersands.
Fix: We replaced all ampersands with the word “and” in Heading1s.
Ensure unique page titles
Issue: In a few instances, Heading1 titles were reused for a child topic (e.g., Heading2). However, both Heading1 and Heading2 paragraph styles were set in the Style Designer with Page break priority=1, Table of contents level=2, and Wiki heading level=1, which means that all Heading1 and Heading2 topics start on a new page. This resulted in wiki pages with titles like “Installing our software” and a child page “Installing our software 2”. It was easy to identify these pages by scanning the page tree (table of contents in the sidebar) in the Confluence wiki.
Fix: We ensured that Heading1 and Heading2 titles were not duplicated.
Clean catalog of cross-reference tags
Issue: Our FrameMaker files had accumulated many unnecessary cross-reference tags, many of which were obsolete or duplicates.
Fix: We deleted the cross-reference tags that we no longer used. The Cross Reference Rules dialog in ePublisher became much easier to work with as a result.
Update Figure and Table paragraph tags
Issue: The Figure and Table paragraph tags in our source files were numbered. Numbered figures and tables did not seem to make sense in a wiki, where users could search for, and read, topics in a non-linear way.
Fix: We replaced Figure with FigureWiki tags, and Table with non-numbered Heading2s. Then, we updated all cross-references to them.
Break up long sections
Issue: Long sections that were not broken up with a Heading1 or Heading2 were acceptable in print documentation, but ended up being very long pages in the wiki. On the web, shorter is better: shorter sentences, paragraphs, and pages.
Fix: We identified pages that looked too long and divided them into smaller topics.
Put graphics in empty paragraphs
Issue: In converted files, some graphics were inserted at the end of sentences. Some also interrupted list numbering.
Fix: We inserted graphics in empty paragraphs in the source files. We used the following paragraph styles:
Use NumberedCont paragraph for the list numbering to continue numbering and have the graphics indent correctly.
Use BulletCont paragraph for graphics to indent within a bulleted list.
- Use Body/CellBody for graphics not in a list.
Use WikiCategory marker
Not an issue. We created a WikiCategory marker to allow us to specify labels in Confluence.
Next: Creating the stationery in ePublisher for Confluence wiki