About Topic Reviews and Contributions

Here is what you can accomplish with reviewers and contributors through the use of the X-Edit products.

• Reviews You can quickly email topics to other individuals for their feedback and/or changes. After inserting annotations (comments) or making changes to a topic with MadCap X-Edit or X-Edit Review, reviewers can send the topic back to you. You can then accept those comments or changes so that they are added to the source file.
• Contributions Authors, developers, or other individuals in your company can use MadCap X-Edit or X-Edit Contribute to create new documents and files, which can be incorporated into your Flare project. These documents can also be exported to PDF, XPS, and XHTML outputs.

The following diagram shows how X-Edit, X-Edit Contribute, and X-Edit Review work with MadCap Flare and Blaze.

Following are some of the key features available for topic reviews and contributions.

• Annotations You and other individuals can insert comments and notes next to content in a topic. Annotations do not become part of the actual content; they are simply comments for your internal use. When other individuals send you reviewed topics (FLTREV files) that contain annotations, you can accept those annotations so that they are copied into the source file in your project. See Inserting Annotations.
• Contribution templates In order to accommodate and assist the contribution process, you can create contribution templates for other individuals to use. These templates are topic files that can be crafted to already have certain pieces in place (e.g., text, formatting, locked regions) and make certain ancillary files available (e.g., variables, condition tags, style sheets) to the contributor. After using the template to create a new document in MadCap X-Edit or X-Edit Contribute, the contributor can send it to you, and you can then make the document part of your project. See Creating and Sending Contribution Templates and Sending Contribution Templates.
• Emailing Thanks to tight integration with Microsoft Outlook, topics can quickly be emailed back and forth for review. The necessary file is automatically attached to the email, and the default email message text is provided. You can also save email messages to use again in the future, and you can add email addresses to an address book for enhancing quick file transfers. See Sending Topics for Review, Creating and Sending Contribution Templates, and Sending Contribution Templates.
• Locks This feature is not limited to reviews and contributions, but it comes in quite handy in those processes. You can put a lock on certain parts of a topic or contribution template, which lets individuals see those areas, but not modify them. See Locking Elements.

• Review mode/Edit mode In the Review toolbar, you can toggle between the traditional Edit mode—which lets you add and change content, as well as insert annotations (comments) next to content—and the Review mode, which is used only for inserting annotations. You might use the Review mode, for example, if you simply want to insert notes next to topic text for your own internal use. When you are in Review mode, the cursor changes (displays a bubble icon) in order to reflect this fact.

  

  

Following are the steps involved in the topic review process.

1. (Optional) You—Open topic Open topic that you want to send for review. See Opening Topics.

   If you intend to send multiple topics for review at once, you do not need to open each topic. Instead, you can use the Project>Send For Review option when you get to step 3.

2. (Optional) You—Lock elements If you want to ensure that the other individual(s) do not make changes to certain portions of the topic, you can apply locks to specific elements within it. See Locking Elements.

3. You—Send topic to reviewers Email one or more topics to other individuals for review. When doing this, you can specify whether the reviewers should be allowed to edit the file or not. See Sending Topics for Review.
4. Reviewers—Open file The reviewers open the email message and double-click the attached file, which has an .fltrev extension. From the Open With dialog, a reviewer selects one of the available options and clicks OK. In most situations, the reviewer will select one of the first two options.
   • Open for review in X-Edit Review The Save As dialog opens, which prompts the reviewer to save the file somewhere locally. The file then opens in X-Edit Review.
   • Open for edit in X-Edit The Save As dialog opens, which prompts the reviewer to save the file somewhere locally. The file then opens in X-Edit.
   • Save archive to other location This option allows the reviewer to save the file first and then later double-click it from that location to open it in X-Edit or X-Edit Review.
   • Add to Returned Topics Folder in corresponding Flare project This option places the file in the inbox of the same Flare project on the reviewer's computer. The project must have an identical path as your project. In most situations, reviewers will use one of the previous options, rather than this one.
5. Reviewers—Insert annotations/make edits After the file is saved, it opens in X-Edit or X-Edit Review. The reviewer inserts annotations and/or makes changes to the file (if you have allowed it).
6. Reviewers—Save and return file After finishing inserting annotations and/or making edits, the reviewer saves the file and returns it to you.
7. You—Open File Open the email message and double-click the attached file, which has an .fltrev extension. From the Open With dialog, select one of the available options and click OK. In most cases, you will probably select the final option to place the reviewed topic back in your project.
   • Open for review in X-Edit Review The Save As dialog opens, which prompts you to save the file somewhere locally. The file then opens in X-Edit Review.
   • Open for edit in X-Edit The Save As dialog opens, which prompts you to save the file somewhere locally. The file then opens in X-Edit.
   • Save archive to other location This option allows you to save the file first and then later double-click it from that location to open it in X-Edit or X-Edit Review.
   • Add to Returned Topics Folder in corresponding Flare project This option places the file in the inbox of your Flare project.
8. You—Take action on file Do one of the following, depending on the option you selected.
   • If you opened the file in X-Edit or X-Edit Review You can use X-Edit or X-Edit Review to insert your own annotations and/or edit the topic, then send the topic back to the reviewer.
   • If you returned the topic to your project You can open your inbox in the Topic Reviews window pane to access the reviewed topic (see Viewing Reviewed Topics in Inbox). From there, you can select to accept the topic or accept the annotations within it.
     • Accept topics If you use this feature, the reviewed topic will overwrite the source topic. The new topic will therefore include all annotations and edits from the reviewed copy. The reviewed topic will also be removed from the inbox. See Accepting Reviewed Topics.
     • Accept annotations If you use this feature, a dialog opens, which lets you select which annotations in the reviewed topic to accept. When you are finished, those annotations will be added to the original topic. The reviewed topic will remain in the inbox until you accept it or remove it. See Accepting Annotations.

If you send topics to reviewers from time, there are a couple of features that can help streamline the process. By associating status file tags with topics and using the File List window pane to select topics for review, you might find that the process is much quicker and easier.

  Best Practice: Use file tags and the File List window pane when sending topics for review.

Following are the steps involved in the contribution process.

1. (Optional) You—Create contribution template If you want to give contributors prepared files and content to use when creating documents, you can create and send contribution templates to them. Otherwise, contributors can simply create new documents using standard factory templates. See Creating and Sending Contribution Templates and Sending Contribution Templates.

   If you want to ensure that the contributor does not make changes to certain portions of the topic, you can apply locks to specific elements within it. See Locking Elements.

2. Contributors—Save template If you send a contribution template to the contributor, that person can save the template in a particular location on his or her local drive to be opened later when creating new documents.

   Note: If contributors save the template file, they can do so anywhere on their local drive. However, if you want the contributor to be able to use the template when creating brand new documents in X-Edit or X-Edit Contribute, the template file should be saved to a specific location in that individual's My Documents\My Templates folder ("Documents" in Windows 7 and Vista).

   To do this, the contributor can open his or her "My Documents" folder and create a subfolder named "My Templates." Then, within that folder, the contributor should create another folder named "X-Edit." The contributor should place your template file within it. In other words, the contributor saves your contribution template file to a folder called "My Documents\My Templates\X-Edit."

   Why go through all of this? Because when the contributor creates a new document, he or she can select your template to start the new document with the same elements from the template file. You might use this method, for example, if you plan to periodically receive contributions from a developer and you want that person to always send you topics that contain the same introduction text and use the same formatting. Rather than making the developer perform those tasks (or "fixing" the document yourself after receiving it from the developer), you can ensure that the pieces are all there when the developer first creates the document. Then the developer can simply concentrate on adding content.

3. Contributors—Create The contributor can create a new document in X-Edit or X-Edit Contribute (with or without using your template).

   When creating documents, contributors can either use a standard factory template provided by X-Edit or X-Edit Contribute (by selecting Factory Templates in the New Document dialog), or they can use the contribution template that you provided (by selecting My Templates, if they have previously saved the template to the appropriate folder in My Documents\My Templates\X-Edit).

4. Contributors—Send file After finishing the file, the contributor sends it to you via email. There are options from the X-Edit or X-Edit Contribute interface for doing this.
5. You—Open file Open the email message. If the contributor has sent you an MCCO file, double-click the attached file. From the Open With dialog, select one of the available options and click OK. In most cases, you will probably select the final option to place the file in your project.
   • Open for review in X-Edit Contribute The Save As dialog opens, which prompts you to save the file somewhere locally. The file then opens in X-Edit Contribute.
   • Open for edit in X-Edit The Save As dialog opens, which prompts you to save the file somewhere locally. The file then opens in X-Edit.
   • Save archive to other location This option allows you to save the file first and then later double-click it from that location to open it.
   • Add to Incoming Flare/Blaze Contributions Folder This option places the file in the contributions box of your Flare project. In Windows, the file is placed by default in your My Documents\My Incoming Contributions folder.

   Note: You can also import contribution files from another location. See Importing Contribution Files.

6. You—Accept file If the author has sent you an MCCO file and you have placed it in the contributions box of your Flare project, you can open the Contributions window pane to access the topic (see Viewing Contribution Files). From there, you can select to accept the topic (see Accepting Contribution Files).