M100358: Manual release process

Summary of the process for: 

• Finalizing manuals for inclusion on the product CDs
• Producing PDF masters for printing of the manuals
• Producing online help to ship with the product
• Producing website HTML versions of the complete documentation set.

Updated for latest knowledge of text insets and the trouble they cause.

Manual release checklist

In the standard work area (revision controlled):

Open the book file, and use as the control point for all of the following.

•  Reviewed
  
  
•  Spell-checked
  Select book file then Edit > Spelling checker...
  
  
•  Document fields correct
  The contents of the document information fields are recorded in the PDF files that are shipped with the product. 
  
  1. In the Book file, select the Book and all component files.
  2. From the File menu, select File Info....
  3. Check that the Author field is set to "Technical Communications".
  4. Ensure that the Title and Subject fields are identical and contain the manual name as it appears on the title page.
•  Part number updated
  1. Open the forematter file (typically forematter.fm).
  2. Update the part number (minimally by bumping the edition number). Part numbers are constructed in the following way: 
     Example: MGS6-RMG2141
     1. Product name code: MGS
     2. Product major release version: 6
     3. Separator hyphen: -
     4. Manual/format code: (eg) RMG
     5. Design style: 2
     6. Product minor release numbers: 14
     7. Edition/print-run: 1 
•  Previous product release numbers removed
  1. Search the entire book for any occurrence of the previous product release number (for example, at release 6.2 search for 6.1; at 6.2.4 search for 6.2.3; and so on).
  2. Fix.
•  Numbering standardized (print/PDF production only)
  1. Select following chapters as appropriate, and then use Format > Document > Numbering to set the values shown.cha
  2. formatter: Chapter 0 (zero); Page 1 Roman (xiv)
  3. TOC: Chapter Follow previous chapter; Page Follow previous chapter
  4. First real chapter: Chapter 1 Numeric; Page 1 Numeric
  5. Rest of chapters including Index: Chapter Follow previous chapter; Page Follow previous chapter 
•  PDF settings standardized (print/PDF production only)
  1. Select all chapter files.
  2. Format > Document > PDF Setup...
  3. Check Setup is right for this output (for example, Standard for online, Press for printables)
  4. Check Bookmarks are selected (not for print), and that the following paratypes are selected and indented appropriately:

  1.     .AppendixTitle                 
         BookTitle2
         .ChapterTitle1
         .ChapterTitleIndex
         ..Heading 1
         ...Heading 2
         ...Heading 2 Help           
         ...Heading 2 Preferences   -- Prefs Online PDF only
         ....Heading 3
         ..Heading A

•  Do you need to switch image sizes? See KB100647.
  Run S:\Documentation\Tools\imageSwitch\ManualsUseENProc300Color.bat to produce PDFs andManualsUseENProc96Color.bat for Help.
  
  
•  Check for missing text insets or images
  1. Select all the document files in the book, right-click and select Open.
  2. As each file opens, resolve any missing images.
  3. If warnings about unresolved text insets are displayed, search for and resolve these. 
•  Color settings standardized

  If FrameMaker displays color errors, you will need to fix the color settings:

  1. To fix colour settings (which must be the same across all files), select all files and use View > Color >Definitions... 
•  Colored text made black (Print only)

  Colored text (such as blue for URLs) will print really yucky and grey and spotty in the bound manuals. Make any colored text black.

•  Glossary up-to-date

  The Glossary is generated from a database. Ensure that the most recent Glossary is generated and included in the ManageSoft Guide. See KB article 100324 for instructions to generate the Glossary.

•  Prepare for indexing
  1. Turn Index paragraphs (type Index, conditional text Index) into index markers: 
     Select the book, and from the Indexing menu, select Update All Markers.

     Note: This technique does not create the index markers in included files. Our working policy is that these files should be saved with up-to-date index markers at all times. If you are an untrusting type, open them all and insert the markers. They are conveniently stored in subdirectories called "components" so that you can select them all in Windows Explorer and open them in FrameMaker. Don't forget the "Searching acros manuals" one which is stored in \doc\src\templates!

  2. Hide Index conditional text: from the Indexing menu, select Hide Index Entries OR hide the conditional text following the instructions in the following step. 
•  Conditional display standardized
  1. Select all document files in the book.
  2. View > Show/Hide Conditional Text.
  3. For PDF manuals, show Print Only and PDF only (latter displays the verso of the title page).
     For the version of ManageSoft Reference: Preferences for Managed Devices that will be supplied for online use (not the hi-res version for print), also show Online Only. This (in conjunction with selecting Heading A and Heading 2 Preferences the PDF bookmarks) is required to get PDF bookmarks of A - B - C, with preferences listed alphabetically below them.
  4. Click Set. 
•  Master page usage standardized (print/PDF production only)
  1. Open each chapter file one by one and complete the following checks. Master pages are applied through Format > Page Layout > Master Page Usage.
  2. Copyright/legals page in Forematter has no headers or footers. Apply custom master page: None.
  3. First page of chapter has no header or footer. If not, apply the FrontCover master page.
  4. For normal chapters, apply Left/Right master page from the second to the last page of the chapter. Glossaries are special.
  5. If the last page with chapter content is odd (so that there is a blank even-numbered page to finish the chapter), make sure that the last page has the BlankLastLeft master page applied.
  6. First page of Index uses Index cover master page.
  7. Rest of index uses IndexLeft/IndexRight master page from the second to the second last page of the chapter. Last page uses the appropriate master page (one of IndexLeft/IndexRight/BlankLastLeft).
•  Change bars cleared (for production)
  1. Highlight all chapter files
  2. Format > Document > Change bars...
  3. Check Clear all changebars and click Set.
•  Update the book
  1. Select the Book file.
  2. Edit > Update (or click the sparkly book icon in the lower-right frame of the window).
  3. Ensure that all renumbering will occur, and that the TOC will be regenerated (needs a checkbox PLUS membership in the list of regeneration).
  4. Fix any errors.
  5. Repeat until there are no more errors.
  6. If you are working on an online help (_olh) book from which .chm files are produced, ensure that the book contains timestamp.fm before the index file. Copy one from an existing project if necessary. This is the timestamp used to check that the version of online help included in a release is "the right one" (make a note of the timestamp from the file you check in, and ensure that the build has collected the right one). 

If publishing PDF files or printing

•  Tweak the Table of Contents (for PDFs and print)
  
  1. Check the top of the generated TOC, and if necessary add the heading "Contents" in para format Heading 1 noTOC.
  2. Ensure that "Contents" does not appear as an entry in the TOC itself.
  3. Ensure that the appearance of the TOC is standard. If need be, copy the TOC definitions from a known-good file (Reference pages) and paste in the Reference pages of your TOC.
  4. Check headers perform as expected though TOC, including first page and (if necessary) blank last left.
  5. Go through the TOC and add forced returns in chapter headings that are too long for the format.
  6. With headings that are too long for the column, seriously consider going back to the source chapter and shortening the heading. PLEASE! 
     If that's impossible, consider inserting a hard line break in the heading within the source text. 
     If both those are impossible (really??), shorten (edit directly) the version in the TOC. 
     If that's impossible, control the line breaks and tabs manually for the best possible result.
  7. Check that page breaks occur at sensible places, and manually adjust if necessary. 
•  Generate PDF
  1. Select File > Save Book As. Save as a PDF file with the correct settings for the output purpose. For example, for e-Books on the product CD-ROM:
     • Quality is set to Standard
     • Set the "Open book to page" field to blank (delete its default contents). This causes the PDF to open at the title page.
     • Page size is 19cm x 23 cm.
     • Bookmarks are generated
  2. Finalize the PDF in one of these ways:
     • For print: Create a PDF of the front title page only, this time with crop marks set to Western. Name this sensibly as _PAGE1_CROPMARKS.pdf or similar. It will assist the print house to crop accurately.
     • For online: Open the PDF file in Acrobat (not Reader) and verify that the fields in File > Document Properties > Summary (shortcut Ctrl+D) reflect the contents from your FrameMaker File > File Info... settings. Adjust if necessary.(If this is a draft for testing, add an Adobe stamp on the front page.) 
•  Validate against checklist (PDF)
  1. Open the Excel checklist available in \doc\src\templates\PDF_Production_Checklist.xls, and save a copy into the same directory as the PDF file with a naming convention like signoff_[volume]_[date].xls. For example: signoff_operations_20030314.xls
  2. Skim through the PDF manually page by page to ensure that everything is perfect. Check each item in the checklist.
  3. If your book contains a schema, confirm that the schema appears in the PDF TOC.
  4. When the checklist is completed, save it to the same directory as the PDF file (normally the working directory for the manual's book file).
  5. [OCT 2006: Drop this step until Adobe Reader stops warning users about interactive form fields on digitally-signed documents.] Digitally sign the PDF file, giving the checklist filename as the location (see KB 100435 for more information). 
•  Store output and check-in working files
  1. Move the validated PDF file to \doc\output\<release_number>\<suite_acronym>\. In that location, add it to subversion, and check in with an appropriate message.
  2. Backup files are not versioned. You may wish to clean your working directories by conducting a search in Windows Explorer, starting from the folder for this manual, for files that contain the text backup, and deleting the files from the results pane. This is a pretty safe method to avoid deleting the wrong file by accident.
•  Check in the finalized files
  To work around the problems of text insets, you will complete this work in a separate area. So check in the finalized files first. 
  
  
• Loop back for each PDF manual
  Switching directories in the next section will mess up cross-references and text insets, including across manuals. Cycle through all the manuals for the work "above the line" and then change all directories at once.

If generating online documentation or HTML help, switch to non-controlled files and continue

•  Clean up the temporary working folders
  The temporary working area consists of copies of your checked in directories made temporarily in the same directory tree, but never checked in, and always cleaned up and restarted from clean. As well, there are temporary output directories.
  1. In the source tree, remove any old working copies of directories, typically ending in _FLAT (and an optional release number).
  2. Remove the temporary output directory in E:\tmp for the output you are preparing.
•  Export to a working area 
  
  1. In Windows Explorer, rename the folders needed to compile the help or online doco by adding a standard suffix such as _CHKIN. One like this identifies the directory which is always the one to check in. (Working copies must never be checked in.) 
     If a directory remains locked by a process, remember you can right-click and choose Unlocker to find what application has exerted the lock.
  2. Start a command window.
  3. Use the command svn export URL PATH to export a clean copy of each original directory you just renamed into the workspace (this gives us a clean copy without SVN files and able to be messed about with impunity). You can find the URL by browsing the repository. Use the standard folder name so existing WebWorks targets work! For example:
     E:\>svn export http ://svndoco/managesoft/project/trunk/doc/src/ECM/ E:\doc\src\ECM
•  If you just completed the PDFs, switch image sizes again. 
  Run S: \Documentation\Tools\imageSwitch\ManualsUseENProc96Color.bat to produce Help or website documentation.

The remainder of these instructions are applied to the exported, not revision-controlled area. Loop through the following four steps for each manual.

The Help book files are as follows:

•  Validate against checklist (CHM)
  1. Open the Excel checklist available in \doc\src\templates\PDF_Production_Checklist.xls, and save a copy into the same directory as the PDF file with a naming convention like signoff_[volume]_[date].xls. For example: signoff_olh_20030314.xls
  2. Skim through the CHM manually page by page to ensure that everything is perfect. Check each item in the checklist.
  3. When the checklist is completed, save it to the same directory as the CHM file (normally the multivolume/output working directory for the manual's source). 
•  Rename working directories, clean up
  1. Save the flat working directories by renaming them with a standard suffix of the form _FLAT_<Rel-no>(for example, ECM_FLAT_8-1).
  2. Leave these in place until next compile. (This gives you a working copy of this product, in case you need intermediate compiles with the opposite product in the interim.)
  3. Rename the _CHKIN directories to their proper names, and checkin any corrections you made during the process.
•  Tag the release in subversion
  1. Make sure that everything is checked in, including modified images.
  2. Run the subversion repository browser (right click a directory and select Repo-browser), and locate the directory for storing tags. Currently this is http ://svndoco/managesoft/project/tags/. Handy to copy this to clipboard.
  3. In the Repo-browser, right-click the trunk folder and select Copy to.... In the dialog that appears, paste the tags folder name, and add a new folder name for the current release. Example: http:// svndoco/managesoft/project/tags/ecm821.  Click OK.
  4. In the second dialog that appears, add a comment to explain what you're doing. Example: "Tagging ECM release 8.2.1". Click OK.