Self-Service Documentation Updates for Git Users

Transcription

1 Self-Service Documentation Updates for Git Users November 2017 Quick Start The Documentation Production Team provides a Self-Service Documentation Updates tool that automates some aspects of the publishing process. This allows you to easily update your online documentation without the assistance of a Documentation Production Specialist on the live or beta websites for Novell.com and NetIQ.com and on the documentation staging server. You can push updates as needed to address enhancement requests, user comments, bugs, patches, and errata such as typos and missing graphics. You submit a build request to trigger an automated update of the online HTML, PDF, and graphics for one or more specified manuals, quick starts, release notes, readmes, or technical references for an existing documentation site. The update automatically purges the old doc set s files before it publishes the updated doc set s files. This site preparation prevents the existing files from being orphaned if you remove or reorganize a guide s content, and ensures that customers can access only the latest information. A request can also update the document s Last Updated date on the product s online TOC. When the publishing process completes successfully, you automatically receive an notification that summarizes the updates. If the process fails, you receive a notification identifies the issue that triggered the failure. Of course, using the self-service method is voluntary. If you prefer, you can also request Documentation Production to push these types of updates for you as described in Documentation Services Bugzilla Requests. This Quick Start describes the requirements for using the tool, how to prepare a build request file, how to submit the file to trigger the update, and how you know that the process succeeded. It is intended for DocSys FrameMaker users with documentation projects on the Git version control server. IMPORTANT: If your documentation project is on a different version control system, see the appropriate document: Self-Service Documentation Updates for Subversion Users Self-Service Documentation Updates for Perforce Users What s New for Self-Service Publishing NOVEMBER 2017 Subversion Users: Self-service documentation updates are now available for the website. Use the docset="microfocus" in the <product> tag. The ability to update the date on the TOC is not available for this site. Use toc_update="n" in the <guide> tag, or do not include the option. Benefits The Self-Service Documentation Updates process: Provides flexibility in the documentation updates process Automates the process for pushing documentation files from the version-control repository to a documentation website Allows writers to submit a request that triggers an automated update for online documentation Requirements For Git users, the Self-Service Documentation Updates process requires the following: Your documentation project s files must reside on a supported Git version-control repository. Currently, Doc Production supports only the Documentation Services Git SCM server ( secmgmtgit.provo.novell.com:8443/scm/). The product development team creates the product repository, and

2 then provides access to the Doc Production team and the writer. The Doc Production Team creates a Documents folder and other necessary files in that folder for you. The directory names in your guide s version-control workspace must conform to the directory structure described in Your Book Folder in the Authoring Guide. The directories in your document folder are created automatically when you use the latest DocSys toolset for FrameMaker. The target live or beta or wwwtest documentation website must already exist for the specified product release. The keywords point to different publication areas. For example, the following websites are set up for the PlateSpin Transformation Manager product: The PlateSpin Transformation Manager 1.0 live website: The PlateSpin Transformation Manager 1.0 Beta beta website: platespin-transformation-manager-1/ The PlateSpin Transformation Manager 1.1 wwwtest website: platespin-transformation-manager-1-1 Each guide to be updated must already be published on the target documentation website. A build request XML file defines the following: A single target documentation website (live, beta, or wwwtest) for a product. The URL for the Git repository path. For each guide, the target path in the repository to its XML or HTML file (as appropriate to the guide type), including the file name, but excluding the root folders for the repository path. For each guide, whether to update its PDF file. Both the online PDF and the All PDFs file will be updated. For each guide, whether to update its graphics files. (Optional) Comments. (Optional) For each guide, whether to update its Last Update date in the Table of Contents (TOC) on the product s documentation website, and whether to use the run date of the request or a specified date. NOTE: A request cannot be used to update only a PDF file, a graphic file, or the TOC date independent of an online HTML update. Thus, it cannot be used to update guides that are published as PDF only. A request cannot update the product description, guide names, or entries for the product s online TOC. For these types of changes, you must submit a request to the Documentation Production Specialists. (Log in to Bugzilla ( and submit a request for Doc Tools > Doc Production.) The build request file must contain well-formed, valid XML. Before you submit a build request, ensure that you commit to the version-control repository the latest version of the following files for each specified guide: XML file (or the Web Single HTML (single file for company doc site) file for guides that use the Readme, Release Notes, Quick Start, or Technical Reference format in FrameMaker) PDF file Graphics files Submissions must be made from a secure location. You submit the request to an FTP site behind the company firewall. If you are off-site, a VPN connection is required. Planning for Self-Service Documentation Updates The Self-Service Documentation Updates process is easy to use. The tips in this section can help you use it effectively and consistently. Setting Guidelines on page 2 Preparing a Template Build Request File on page 3 Committing Files to the Version-Control Repository on page 3 SETTING GUIDELINES The self-service publishing process is designed to allow any writer to submit update requests. Typically, individual writers update their own assigned guides. However, each writing team should determine how to handle self-service updates. Documentation Production Specialists can also take advantage of this process to publish updates. Common self-publishing guidelines include the following: Allow experienced writers to submit requests to update their own assigned documents. Allow only the lead writers to submit requests to update a guide with multiple authors. 2

3 Designate one or more writers to submit requests for an assigned set of documents for a particular release cycle. This allows you to synchronize documentation updates for a scheduled maintenance or hot-fix patch release that involves most or all of the project s guides. Designate one or more writers to submit requests on behalf of other writers on the team. This can be useful if the team has newly hired writers, novice writers, or interns. PREPARING A TEMPLATE BUILD REQUEST FILE Each self-service update request is defined in a build request file. This is an XML file that contains information about the target publication area and which guides to publish. Each build request file can update one or more guides for a target product release s live, beta, or wwwtest documentation website. Creating a template build file for each of your product releases can save time and help ensure mistake-free requests. Each writing team should create a template build request file for each product release that the project supports. Collect the needed information about the guides, create a template build file, test the file, and share it with team members. Writers can use the team s template as the basis for their own request files, and can submit their own requests. For more information, see Understanding the Build Request File on page 3. COMMITTING FILES TO THE VERSION-CONTROL REPOSITORY Before you submit a build request, ensure that the latest XML or HTML file, PDF file, and graphics files have been committed for each affected guide from your client workspace to the version-control repository. If the document contains profiled content, ensure that you have built the desired profiled version and committed its files to the repository. Understanding the Build Request File The build request file defines the target location and one or more guides or documents that you want to update at that location. This section describes the available settings and options. You can see the format and sequence of the basic commands and options in the Build Request Template file (selfserv_git_build_request_template.xml) on the Documentation Development Resources website ( The template also describes the available settings and options. Several project-based sample build request files are available in the Build Request Examples file (selfserv_git_build_request_examples.zip) on the Documentation Development Resources website ( These samples demonstrate how to list multiple guides in a build request file for a given product release version. You can share your team s sample build file by sending it to one of the Documentation Production Specialists for inclusion in the examples file. Download the template and examples. It is helpful to view a sample file in a text or XML editor as you read about the tags and options in the following sections. IMPORTANT: XML code is case sensitive. Tags, attributes, and values should be lowercase. Values must be enclosed in quotation marks. Build Tag on page 3 Product Tag and Attributes on page 3 Guide Tag and Attributes on page 4 Comment Tag on page 5 BUILD TAG The <build> tag is the root element of the XML file. PRODUCT TAG AND ATTRIBUTES The <product> tag provides the product information for the update request. You must specify values for the following <product> tag attributes: docset= Specify "novell" or "netiq". docset="novell" docset="netiq" site= Specify "live" or "beta" or "wwwtest". The live option publishes to documentation/. The beta option publishes to The wwwtest option publishes to wwwtest.provo.novell.com/documentation/ or to wwwtest.netiq.com/documentation. site="live" site="beta" site="wwwtest" product_name= Specify the product name as it appears in the Name= field in the product.ini file, such as "directoryand-resource-administrator-9" or "grouppolicy-administrator-68". product_name="group-policy-administrator-68" 3

4 submitter_ = Specify the address of the person who is submitting the update request. cc_ = (Optional) Specify the addresses of one or more company stakeholders you want to notify about this update. The recipients are automatically cc d on the notification message. Separate multiple addresses with a semicolon and a space. If no cc is desired, remove the cc_ attribute. cc_ ="bob.jordan@microfocus.com" cc_ ="mary.smith@microfocus.com; bob.jordan@microfocus.com" (no entry if no cc is desired) repo_path= Specify the URL to the Git repository that contains your documentation project. repo_path=" secmgmtgit.provo.novell.com:8443/scm/ documentation/doc-production.git" repo_path=" secmgmtgit.provo.novell.com:8443/scm/gpa/gpa.git" repo_path=" secmgmtgit.provo.novell.com:8443/scm/adsg/ adsg.git" Include only one product tag entry in build request file. Place the product command on a single line. The following examples are shown on multiple lines for readability: Example: Product tag with cc. <product docset="netiq" site="live" product_name="group-policy-administrator-68" submitter_ ="john.doe@microfocus.com" cc_ ="mary.smith@microfocus.com; bob.jordan@microfocus.com" repo_path=" scm/gpa/gpa.git"> <!-- one or more guide entries --> <!-- optional comment --> </product> Example: Product tag with no cc. <product docset="netiq" site="live" product_name="group-policy-administrator-68" submitter_ ="john.doe@microfocus.com" repo_path=" scm/gpa/gpa.git"> <!-- one or more guide entries --> <!-- optional comment --> </product> GUIDE TAG AND ATTRIBUTES The <guide> tag provides the information needed to publish an individual guide. Specify the target path in the repository to its XML or HTML file (as appropriate to the guide type), including the file name and extension, but excluding the root folders for the repository path. Use a backslash as the separator between the path elements. The leading backslash is optional. The XML file is used to create the multiple HTML output that you see for a typical guide s online HTML. Some guides, such as those that use the Readme, Release Notes, Quick Start, or Technical Reference format, are exported from FrameMaker using the Web Single HTML (single file for company doc site) export option in DocSys. You specify the path to the XML file or to the single HTML file, whichever is appropriate for the guide type. To publish the profiled version of a guide, ensure that you provide the URL path to the profiled version of the XML or HTML, whichever is appropriate for the guide type. Pushing updates for the related PDF file and graphics files is optional. You must specify values for the following <guide> tag attributes: img= Specify "y" if you have new or changed graphics, or "n" if there are no graphics changes. img="y" img="n" pdf= Specify "y" if you have changed the PDF, or "n" if there are no PDF changes. pdf="y" pdf="n" comment= (Optional) Specify a brief guide-specific description of the changes made or a reason for updating. If you have no comment, use a value of "none", or remove the comment= attribute. comment="ucxxxxx, bugxxxxx, edits" comment="typo in command on p34" comment="none" toc_update= (no entry; no comment) (Optional) Specify "y" to update the guide s Last Update date in the TOC on the product s documentation website. By default, the run date (local 4

5 time in Provo, UT) is used as the new date. You can specify a preferred date to use by adding the toc_date= attribute. If a TOC update is not needed, specify "n", or remove the toc_update= and toc_date= attributes. If toc_update="n", the toc_date= attribute is optional and is ignored if it is present. toc_update="y" toc_date="08/16/2016" (update) toc_update="y" toc_update="n" toc_date="08/16/2016" toc_update="n" update, use run date) (no update) (no update) (no entry; no update) toc_date= (Optional) If toc_update="y", use this attribute to specify the preferred date to use for the guide s Last Update date in the TOC on the product s documentation website. The date format is "mm/dd/ yyyy", with two digits for month and day, and four digits for the year, such as "08/16/2016". If toc_update="y" and the toc_date= attribute is not present, the run date (local time in Provo, UT) is used as the new date. If toc_update="n", the toc_date= attribute is optional and is ignored if it is present. The guide s Last Update date is not modified in the TOC. The toc_date= attribute enables you to do the following: Correct the current Last Update date Use a future date for a pending Beta or Support Pack release Use the same date as the guide s front cover for a silent documentation update toc_update="y" toc_date="08/16/2016" toc_update="n" toc_date="08/16/2016" toc_update="n" (update) (no update) (no update) (no entry; no update) Include one guide entry for each guide that you want to publish for a release version. There is no restriction on the number of guides that you can list in a single build request file. Place each guide entry on a single line. The following examples are shown on multiple lines for readability: Example: Target path for a book XML file. <guide img="y" pdf="y"> \Documents\frame\dra_user\xml\dra_user.xml Example: Target path for a profiled book XML file. <guide img="y" pdf="y"> \Documents\frame\dra_user\xml\manual\dra_user.xml Example: Target Path for a Web Single HTML file (Readme, Release Notes, Quick Start, or Technical Reference). <guide img="y" pdf="y"> Example: Add a comment for the guide. <guide img="y" pdf="y" comment="bugxxxxx"> Examples: Update the date in the TOC. <guide img="n" pdf="y" comment="bugxxxxx" toc_update="y" toc_date="08/16/2016"> <guide img="y" pdf="y" comment="bugxxxxx" toc_update="y"> Examples: Do not update the date in the TOC. <guide img="y" pdf="y" comment="bugxxsxxx" toc_update="n" toc_date="08/16/2016"> <guide img="n" pdf="y" comment="bugxxxxxx" toc_update="n"> <guide img="n" pdf="y" comment="bugxxxxxx"> COMMENT TAG (Optional) The <comment> tag provides a general statement about the purpose for a build request. Use only one <comment> entry per build file. Place the entry after the guide entries. If you have no comment, use a value of none, or remove the <comment> tag. 5

6 <comment>hotfix 1 release</comment> <comment>sp1 Feature Release 1</comment> <comment>sp2 Beta 2 Refresh</comment> <comment>none</comment> Preparing a Request (no entry; no comment) The submitter personalizes the build request file to identify the target update location and the guides to publish for this request. When you are ready to publish: 1 Ensure that you update the guide, export the XML or single HTML file, and export the PDF. 2 Ensure that you commit the latest files and graphics to the version-control repository. 3 Prepare a build request file. For tag and attribute usage information, see Understanding the Build Request File on page 3. Uncomment the guide command line for each book you want to push. The following character sequences appear before and after hidden (commented out) lines. <!-- One or more lines that are hidden. --> To push a subset of the listed guides, you can comment out the full list, then copy and paste the appropriate lines below it. 4 Save the file. 5 Verify that you have well-formed XML. Open the XML file in a Firefox web browser, or drag and drop the file to the open browser window. If the code is well-formed, the XML file is displayed in the window. If the code is not well-formed, the browser should highlight the invalid XML in the file. Make corrections as needed in the file and try again. Submitting a Build Request File You submit the build request XML file to the Documentation Services FTP server. You can access the FTP server by using the Windows Explorer file browser or any FTP access tool, such as FileZilla. FTP Server Information: Host: docproduction01.blr.novell.com Username: root Password: root To use the Windows Explorer browser: 1 Launch a Windows Explorer file browser window. 2 In the Location field, replace the local file path with: ftp://docproduction01.blr.novell.com 3 When you are prompted, log in with the FTP user name and password (root, root). In a Windows Explorer file browser, you can save the password to log in automatically in future sessions. 4 Drag your request XML file to the git subfolder in the file browser window. The XML file must be uploaded to the git subfolder and not outside it. You can alternatively open the git folder, and then drag the XML file to the file browser window. Wait for the file to upload. The presence of the file triggers the automated update process. The request is queued and processed in turn with other requests. You cannot cancel a queued request. You can submit another request for the same guide if needed. The subsequent request is queued and processed in turn; it does not replace the currently queued request. 5 Wait for the notification. You should receive an notification when the job finishes or fails. The process can take from 20 minutes up to one hour if the server is busy. The automated reply is from sender Documentation Services. The subject line includes the name of your build request file, such as Self-Service Documentation Update - eric_gpa_build.xml. 6 Review the notification to verify that the job was successful. If it was not successful, fix the problem and try again. The notification identifies only the issue that triggered the failure, and does not provide an exhaustive analysis. Other problems might exist. 7 If you require an update to the product's online TOC page (such as for product description changes, book name corrections, or new entries), submit a request to the Documentation Production Specialists. (Log in to Novell Bugzilla ( and submit a request for Doc Tools > Doc Production.) 6

7 Verifying the Updated Guides The notification verifies that files were pushed from your version-control repository to a target location, as determined by the settings and information in your request. Verify that the guides were updated as you expected them to be. The following examples shows the information included in a notification: This is an automated reply to a Self-Service Documentation Update request for catherine_psforge_live_sspub_request.xml. Submitted: August 03, :57:33 MDT UTC-7 hours Completed: August 03, :59:04 MDT UTC-7 hours DocSet: netiq Site: live Product name: platespin-forge-11-2 URL: This request successfully updated the following guide(s): Book name: forge_11-2_relnotes Graphic Update: Yes PDF Update: Yes ToC Update: Yes Purge: Yes HTML file name: forge_11-2_relnotes.html Created: August :46 PDF file name: forge_11-2_relnotes.pdf Created: August 03, :47 Zip PDF file name: forge_11-2_relnotes.pdf Created: August 03, :47 URL: forge-11-2/forge_11-2_relnotes/data/forge_11-2_relnotes.html Comment: chinese graphics Product comment: added bug Full Replication Breaks Differential Backup for SQL Server to known issues For each guide, please verify that the HTML, PDF, and graphics are in the published location. You should also verify that the reported file creation dates match the dates you expected to be available in your version-control repository. If the dates do not match, commit the correct version of files to the repository and try again. Please review each relevant item in the Online Documentation Checklist ( index.php?title=online_documentation_review_checklist) and address any errors or additional changes as soon as possible. If you have questions or issues, please log in to Bugzilla ( and submit a request for Doc Tools > Doc Production. Attach the submitted XML file and the notification to the bug. You can also contact one of the Documentation Production Specialists. Generating Reports about Update Requests The Self-Service Documentation Updates Reports tool is designed to help production specialists monitor the selfservice update requests. Writers, team leads, and managers might also be interested in the data. 1 Launch a web browser, then go to the Self-Service Documentation Updates Reports tool for the Git build: gitssdocbuild/ 2 Select one of the following report types: Detailed - Last 7 days Detailed Statistics by date Statistics by product name Statistics by submitter Detailed - Product & submitter Update frequency History Failures 3 For detailed reports, you can specify the Start date and End date of the desired reporting period. (Click the calendar icon, locate the month, then click the day.) 4 For a Detailed - Product & Submitter report, specify the following information: Product name: (Mandatory) Specify the product name as it appears in the Name= field in the product.ini file, such as group-policyadministrator. Submitter name: Specify the address of the person who submitted the build request. You can also specify a character string that is part of the user s corporate user name. Leave the field blank for all submitters. For example: john.doe@microfocus.com (specific ) smith (character string) (leave blank for all submitters) 5 For a History report, specify the following information: Product name: (Mandatory) Specify the product name as it appears in the Name= field in the product.ini file, such as group-policyadministrator-68. Guide name: (Optional) Specify a single guide name, a character string that occurs in the name of one or more guides, or leave the field blank to report all guides. 7

8 For example: soapdriver.xml (specific guide) admin (guide names contain string) (leave blank for all guides) 6 Click Submit. Legal Notice: for information about legal notices, trademarks, disclaimers, warranties, export and other use restrictions, U.S. Government rights, patent policy, and FIPS compliance, see Copyright 2017 Micro Focus. All rights reserved. 8