Documentation lifecycle

Last modified: Jul 25, 2000

Author: Scott Cox, 497-4710, scox@rsn.hp.com

Audience: MSL-WRM technical writers

Purpose:

Availability:

This document is available in HTML from the following location:

http://mslwrm.rsn.hp.com/iss/procedures/doclfcyc.htm

Acronyms:

I intentionally leave acronyms undefined. Mentors should go through this lifecycle with new writers--explaining acronyms as they go.

FrameMaker products and templates:

Mentors should explain to new writers where to access FrameMaker products and templates.

The lifecycle

When you start a new project, you should:

  1. Determine DART milestones (requires login/password)
  2. Determine training/localization needs
  3. Complete the docplan
  4. Request part numbers
  5. Submit ECN request form
  6. Submit RAPID data (requires login/password)
  7. Develop doc products
  8. Hold a checkpoint meeting with manager
  9. Prepare for IR (ESI) submittal
  10. Submit to the IR (ESI)
  11. Copy files to the USE library web page
  12. Review proof from print vendor
  13. Archive your files/notify SMO
  14. Attend the product ECN meeting

Determine DART milestones (requires login/password)

DART schedules are available on the web at:

http://www-ISU.cup.hp.com:81/

You need a login and password to access this web site. Request the login and password before you need them--it may take several days to get them.

LP milestones to look for include the following:

Man pages are submitted with the software and are due when the software is due.

Your project may also submit release notices with the software.

DART releases are 3 months apart. So, if your DART schedule is not currently available, you can estimate.

Determine training/localization needs

Training needs to be addressed. Please discuss with your manager.

Ask the project manager whether the project's documentation needs to be localized (translated into languages other than English). The project manager may be able to point you to localization contacts.

Complete the docplan

You can get a FrameMaker5 docplan template by selecting the following from FrameMaker5's File menu:

New -> Convex/ -> admin/ -> docplan.template

Information on how to fill in the template is included in the template itself.

Before beginning the docplan:

Request part numbers

Discuss with your manager how you should get part numbers. Products that were developed outside Richardson then moved here may continue getting part numbers through their original sites.

For products that are developed in Richardson, to request part numbers for software manuals:

  1. Access http://mirage/html/software.html.
  2. Select the "Software Part Number Request" link.
  3. Fill in the form.

For products originally developed outside Richardson that moved to Richardson, request doc part numbers following the lead of the project manager. Specifically, if the project manager continues getting part numbers from the original development site, you should do the same. However, if the project manager uses the local procedures to get numbers, you should also use the local procedures.

NOTE: Once you have your part numbers, forward them to the PSP author.

Submit ECN request form

If your documentation is being released independently of a software product, submit an ECN request for the documentation. To submit an ECN request:

  1. Access http://mirage/html/software.html.
  2. Select the "Software ECN Submit Form" link.
  3. Fill in the form.

Submit RAPID data (requires login/password)

You will probably perform the RAPID submittal after you begin your documentation effort. Read the RAPID Submitter's Guide (accessible through the URL given below) before your first submittal.

Check your DART milestones to determine your RAPID submittal schedule. For information on DART milestones, see the Determine DART milestones section.

Fill out the RAPID forms on the web to inform ESI that you have docs coming their way.

You need a login and password to access the RAPID web site. Request the login and password before you need them--it may take several days to get them.

Access RAPID at

http://emperor.mayfield.hp.com/~rapid/

Access RAPID's online help if you have any problems.

NOTE: RAPID does not work with all web browsers. Check the RAPID page for information on which browsers you can use.

If you have issues during or after RAPID submittal, contact the person listed on the RAPID web page.

Develop doc products

The development of documentation differs according to an individual writer's work style. However, the practices recommended below can be incorporated into most documentation projects.

NOTE: Any time you put something out for review, you should read it twice: Proofread and fix the material before it goes out; then, after you incorporate review comments, proofread and fix the material again. Essentially, whenever you put something out for review, it should be as close to the finished product as possible. Mark any sections that you consider less than ideal--informing reviewers of the section's status.

Hold a checkpoint meeting with manager

Meet with Barry Lyden in a checkpoint meeting to verify that your documentation matches the RAPID input.

Bring the following items to this meeting:

This meeting typically takes about ten minutes.

Prepare for IR (ESI) submittal

You use the IR to submit SGML and PostScript versions of your documentation to ESI.

If you are not producing an SGML version of your book, skip Step 3 and Step 7. However, you do still need to create the directory mentioned in Step 3, Substep 1.

To prepare for IR submittal, you should generate the SGML and PostScript for your book or release notice and evaluate how they look in the IR. To prepare for an IR submittal, follow these steps:

  1. Log in to presskit.
  2. Start FM+SGML.
  3. Generate SGML
    1. Create a directory in which to save the SGML; this directory can be a subdirectory to the directory where you keep your FrameMaker files. You can name the directory anything you like.
    2. From the book file, select File -> Save As.
    3. In the Save As dialog, select SGML format.
    4. Specify a file name to save as in the directory you created above--using your part number and the .sgm extension. For example, if your book's part number is B3947-90007, your SGML file should be named B3947-90007.sgm.
    5. Wait for the SGML save to finish.

      Tip: After you start the SGML save, click the "Info" button on the FM+SGML button bar. As soon as the SGML save is complete, the Info window pops up--letting you know the SGML save has finished.

      NOTE: If your SGML save produces any errors or warnings, alter the document in FM+SGML until no error or warnings are generated. You cannot submit to the IR if your SGML save has errors or warnings.

    6. Change directory to where the SGML files are:

      cd /path/to/my/SGML/files

  4. Generate PostScript
    1. From the book file, select File -> Print.
    2. Select all the files in the book for printing.
    3. Select the Print button.
    4. Specify where to place the PostScript file using the field Print Only to File. The file name should include your part number. For example, if your book's part number is B3947-90007, your PostScript file should be named B3947-90007.ps.
  5. Copy the PostScript to the same directory where you saved the SGML.
  6. Put your document in the IR
    1. Start the IR:

      /opt/ws/wsstart

    2. Click the Workspace button on the IR button bar.
    3. Select the Import-Build button on the left side of the IR window.
    4. Locate your SGML file in the "File Browser" window.
    5. Double click your SGML file.
    6. Click the Retrieve button in the "Marked Files" window.

      This processing can take a few minutes.

    7. Specify a book directory name if you desire.
    8. Select Close in the Status Window after you see the "All files processed!" message.
  7. Verify your SGML in the IR
    1. Select your book in the IR window.
    2. Click the View button on the left side of the IR window.
    3. Select the DTEXT_C format.
    4. Select the OK button.
    5. Verify the formatting of the SGML version of your manual or release notice. For detailed information on checking an SGML document online, see How to QA an online book. (http://pasl.rsn.hp.com/USE/procedures/ppbookQA.html)

      If there are formatting problems, first check the structure of your document in FM+SGML. If the structure is appropriate, the style sheets that govern how the SGML is rendered online may need adjustments.

  8. Verify your PostScript in the IR
    1. Select your book in the IR window.
    2. Click the View button on the left side of the IR window.
    3. Select the PS_C format.
    4. Select the OK button.
    5. Verify the PostScript file is acceptable.

Submit to the IR (ESI)

Submitting to the IR requires you to have already performed the RAPID input, which is discussed in the Submit RAPID data section.

Inspect the SGML and PostScript versions of your documentation for proper formatting before you begin an IR submittal.

You submit SGML and PostScript files to the IR. These files are then used to create the Instant Information and hardcopy versions of your document.

NOTE: Be sure to request proofs of your manual and release notes.

To submit to the IR:

  1. Log in to presskit.
  2. Start the IR:

    /opt/ws/wsstart

  3. Click the Workspace button on the IR button bar.
  4. Select your book or release notice in the IR window. (If you have not completed the steps in the section Prepare for IR (ESI) submittal, complete those steps then come back to this step.)
  5. Select the Submit button on the left side of the IR window.

If you have problems with the IR submittal, contact Camille Krug (camille, x4226) or Susie Blackstock (seads, x4544). Also, you can contact ESI for help.

Copy files to the USE library web page

Add PostScript and PDF versions of your manual and release notes to the PASL USE library web page.

  1. Name your files according to their part numbers.

    For example, the book with part number B3947-90013 would have a PostScript version named B3947-90013.ps and a PDF version titled B3947-90013.pdf.

  2. Copy the files to the directory gershwin:/www/use/library/.
  3. Edit the file gershwin:/www/use/browse.htm to point to your new files.

Review proof from print vendor

You should receive proofs within 4 business days of IR submittal.

If you do not receive a proof within 4 days, call the print vendor directly. The current (Jan 99) print vendor is US Print. Their phone number is 925.634.6700.

Try to review the proof and return comments within 2 business days.

An overview of the proof process is online at http://emperor.mayfield.hp.com/~carol/proof.htm.

Archive your files/notify SMO

Because ESI does not archive the books it receives, archiving is done locally. Archiving is initiated by filling out a form on the web. Your FrameMaker files must be on the machine where you launch your web browser.

For release notices, use the link titled "Check in a release notice" on the page at:

http://presskit/forms/relnote.html

For books, use the link titled "Check in a book" on the page at:

http://presskit/forms/bookin.html

Your files are copied to the directory presskit:/work2/submit/part_number.

Also, email is sent to Judy Palma, who then creates the directory presskit:/work2/archive/part_number and archives the submitted files.

Judy Palma also sends a form to SMO informing them that the book is available for ordering.

Attend the product ECN meeting

ECN meetings bring together the parties related to a product release. These parties officially agree (or disagree) that the product is ready for shipment.

These meetings, which take place near the LR date in the DART release schedule, are short and consist mainly of people signing papers.