Style Guide GroupWise Product Documentation August 2013

Transcription

1 Style Guide GroupWise Product Documentation August 2013

2 Legal Notices Novell, Inc., makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. Further, Novell, Inc., makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to notify any person or entity of such changes. Any products or technical information provided under this Agreement may be subject to U.S. export controls and the trade laws of other countries. You agree to comply with all export control regulations and to obtain any required licenses or classification to export, re-export or import deliverables. You agree not to export or re-export to entities on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. See the Novell International Trade Services Web page ( for more information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export approvals. Copyright 2012 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher. Novell, Inc., has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed on the Novell Legal Patents Web page ( and one or more additional patents or pending patent applications in the U.S. and in other countries. Novell, Inc South Novell Place Provo, UT U.S.A. Online Documentation: To access the latest online documentation for this and other Novell products, see the Novell Documentation Web page ( Novell Trademarks For Novell trademarks, see the Novell Trademark and Service Mark list ( tmlist.html). Third-Party Materials All third-party trademarks are the property of their respective owners.

3 Contents About This Guide 5 1 Wording Conventions Capitalization/Punctuation Conventions Optional and Conditional Text Wording Preferences Wording Differences between GroupWise and Synchronizer GroupWise Terminology UI Terminology UI Conventions Doc Updates Section Tagging Conventions InformalFigure, InlineMediaObject FormalPara GUIMenu Index InformalTable For Platform-Specific Information Or Step Tip ULink vs. XRefxxx In Readmes In Guides Profiling Conventions General Rules of Thumb Procedures for Profiled Guides Help System Architecture and Production Windows Client Help WebAccess Help WebAccess Mobile Help Admin Web Console Help Agent Server Console Help Agent Web Console Help Utility Help Free/Busy Service Configurator Help Synchronizer Help Contents 3

4 4 Collaboration Style Guide

5 About This Guide The GroupWise Documentation Style Guide focuses on conventions that should be adopted in the GroupWise documentation (which includes GroupWise itself, the GroupWise Mobility Service, and the GroupWise coexistence solution). Chapter 1, Wording Conventions, on page 7 Chapter 2, Tagging Conventions, on page 9 Chapter 3, Profiling Conventions, on page 13 Chapter 4, Help System Architecture and Production, on page 15 Audience This guide is intended for writers of for the GroupWise product. It is not applicable to other products in the Novell Workgroup Business Unit (for example, Novell Open Enterprise Server). Feedback comments and questions to Jill Boogaard (jboogaard@novell.com). Additional Documentation For standard Novell documentation style guidelines, see the Novell Style Guide ( About This Guide 5

6 6 Collaboration Style Guide

7 1 1Wording Conventions Section 1.1, Capitalization/Punctuation Conventions, on page 7 Section 1.2, Optional and Conditional Text, on page 7 Section 1.3, Wording Preferences, on page 7 Section 1.4, Wording Differences between GroupWise and Synchronizer, on page 8 Section 1.5, GroupWise Terminology, on page 8 Section 1.6, UI Terminology, on page 8 Section 1.7, UI Conventions, on page 8 Section 1.8, Doc Updates Section, on page Capitalization/Punctuation Conventions mailbox when referring to your entire conceptual mailbox (for example, Online mailbox, Caching mailbox, Remote mailbox), but Mailbox in the context of Mailbox folder or when referenced as a feature (parallel to Calendar, for example) Online mode, Caching mode, Remote mote Main window, Main menu, Main toolbar, Home view, Home folder, HTML view, Plain Text view Nav Bar, Folder List, Item List, Mode Selector GroupWise Address Book, Frequent Contacts address book, personal address books All Day Events (no hyphen in the UI) Hostname (one word, expressing Linux bias ;-) ) 1.2 Optional and Conditional Text Use (Optional) and (Conditional) as specified in the Novell Style Guide. At present, these Novell conventions are sporadically applied in the GroupWise User Guides. Use consistently from here on out, updating existing text as practical. 1.3 Wording Preferences Use... in the Name dialog box Avoid... in the following screen shot -- doesn t work when screen shots have been profiled out for help. Wording Conventions 7

8 Use... click Tools > Options > Environment > Cleanup select Option or deselect Option select one or more... Avoid... click Tools > Options, double-click Environment, then click the Cleanup tab -- avoid extraneous words unless the step is ambiguous without them. click Option -- click can be ambiguous because the result can depend on the existing selection when you click. shift+click or ctrl+click for multiple selection -- folks have learned how to multiple-select since the GroupWise User Guides were first written. 1.4 Wording Differences between GroupWise and Synchronizer GroupWise log level Synchronizer logging level 1.5 GroupWise Terminology MTA scheduled event, not MTA-scheduled event Admin-defined fields in the doc, but admin defined fields in the UI Dissociate, not disassociate 1.6 UI Terminology dialog box -- has OK and Cancel buttons group box -- set of options in a dialog box that has its own title page -- edirectory object properties, Installation program window -- browser window, GroupWise Main window drop-down list -- expandable list to select from 1.7 UI Conventions When an option has a text box in the middle of the text, use two underscores to represent the text box. For example, Auto-delete after days. 1.8 Doc Updates Section Make sure that the date in the Front file and the date in the Doc Updates appendix match. List the doc updates in page number order. 8 Collaboration Style Guide

9 2 2Tagging Conventions Section 2.1, InformalFigure, InlineMediaObject, on page 9 Section 2.2, FormalPara, on page 9 Section 2.3, GUIMenu, on page 10 Section 2.4, Index, on page 10 Section 2.5, InformalTable, on page 10 Section 2.6, Or, on page 10 Section 2.7, Step, on page 10 Section 2.8, Tip, on page 10 Section 2.9, ULink vs. XRefxxx, on page InformalFigure, InlineMediaObject For screen shots, use InformalFigure tags with Description tags (for 508 compliance) in Procedure tags. For screen shots and illustrations, use Figure tags with Title tags outside of Procedure tags. For illustrations, pull in the.eps file. For screen shots, pull in the.png file and use 50%-60%. The admin doc has standardized on 60%. The user doc has more variety on screen shot size. The Windows Client User Guide uses 50% for the Main window because 60% is too big. Other screen shots are adjusted to make the text in the screen shot approximately the same size as body text. For icons, use InlineMediaObject tags with Description tags (for 508 compliance). Determine the size of nearby icons that look right, then adjust accordingly. Icons should be sized so you can see what the icon represents, but preferably small enough to not disturb the standard leading. Use screen shots liberally in non-localized text. Jill (and Todd in the good old days...) like this idea. Evelyn is less enthusiastic... Use screen shots sparingly in localized doc. They are expensive to localize. Name screen shot files clearly. Include section indicators. Try to get related files to list together alphabetically. 2.2 FormalPara Lists of fields. (Some groups use tables for lists of fields. It looks nice but is a lot more tagging work than FormalPara tags.) Tagging Conventions 9

10 2.3 GUIMenu In addition to the standard Novell guidelines, use for: Item statuses (Opened, Delivered) 2.4 Index Jill has been the indexing guru to date. This needs to change. 2.5 InformalTable For Platform-Specific Information Linux: Windows: 2.6 Or Use it. Change over to it when updating a procedure. Don t bother with mass replacements. 2.7 Step 2.8 Tip Descriptions of results are not steps, but Para tags with the Step tag. Include where to be when performing the step (for example, In the Main window,.... Secondary (but more convenient) ways to do things. The standard (for 508 compliance reasons) is to document steps using menu items, but many things are more conveniently done from a right-click menu or by dragging and dropping. 2.9 ULink vs. XRefxxx Section 2.9.1, In Readmes, on page 10 Section 2.9.2, In Guides, on page In Readmes In Readmes, you can use the XRefExt tag to cross-reference to guides and into specific sections of guides. However, you can only use ULink to link to the Readme from a guide because the Readme is generated as a single HTML file, and the XRefExt tag doesn t currently account for that. 10 Collaboration Style Guide

11 This looks ugly in the PDF, but the URL is included in case the reader printed the doc and then wants to go to the URL manually In Guides In guides, you can use XRefExt tags to cross-reference to other guides that you own. For example:... in Exploring the Folder List in Getting Started in the GroupWise Windermere Windows Client User GuideGroupWise Windermere Windows Client Help Typically, you include three parts in the external cross-reference, perhaps section/chapter/guide or section/part/guide. You would only have two parts in a high-level cross-references, such as part/ guide or chapter/guide. Tagging Conventions 11

12 12 Collaboration Style Guide

13 3 3Profiling Conventions Section 3.1, General Rules of Thumb, on page 13 Section 3.2, Procedures for Profiled Guides, on page General Rules of Thumb When profiling for help, profile out most screen shots. The user got to the help from the interface. Profile out most conceptual information. The user wants to do a specific task and doesn t care about background information. This saves on localization costs 3.2 Procedures for Profiled Guides Check guides into Subversion profiled for None if you are finished with them for a while. Profiling Conventions 13

14 14 Collaboration Style Guide

15 4 4Help System Architecture and Production Section 4.1, Windows Client Help, on page 15 Section 4.2, WebAccess Help, on page 16 Section 4.3, WebAccess Mobile Help, on page 16 Section 4.4, Admin Web Console Help, on page 17 Section 4.5, Agent Server Console Help, on page 17 Section 4.6, Agent Web Console Help, on page 17 Section 4.7, Utility Help, on page 17 Section 4.8, Free/Busy Service Configurator Help, on page 17 Section 4.9, Synchronizer Help, on page Windows Client Help The Windows client help is single-sourced from the guide. Vestiges of What s This help can be found, but the What s This functionality has not been consistently implemented, since we had no resources to work on it for GW2012. The steps to generate Windows Client help are as follows: 1 In DocSys, open the.book file for the GroupWise Client User Guide. 2 Click Tools > Update. 3 Under Profiling, set the active profile to GenHelp, then click OK. 4 Click Tools > Export > XML. 5 Update the HTML Content Date, then click Export. 6 Navigate to the exported XML file directory (located at gw_guide_userwin\xml\genhelp), then double-click make_winchm_help.bat. This creates a windows help file (.chm) in the current directory. 7 Watch the file creation to check for errors. 8 Copy the CHM file into your own GW install to test it by running copy_winchm_test.bat. 9 Put the updated CHM file into the build by running put_winchm_build.bat (or your customized version of it). 10 Commit the updated release area to SVN 11 Check the next build to make sure it got updated. Help System Architecture and Production 15

16 4.2 WebAccess Help The WebAccess help is single-sourced from the guide. WebAccess does not have context-sensitive help. The steps to generate WebAccess help are as follows: 1 In DocSys, open the.book file for the WebAccess User Guide. 2 Click Tools > Update. 3 Under Profiling, set the active profile to GenHelp, then click OK. 4 Click Tools > Export > XML. 5 Update the HTML Content Date, then click Export. 6 Navigate to the exported XML file directory (located at gw_guide_userweb\xml\genhelp), then double-click make_userweb_help.bat. This creates web help, which is a set of HTML files, in the gw_guide_userweb directory. 7 Watch the file creation to check for errors. 8 To see the updated help on the test server, double click copy_userwebwin_test.bat or copy_userweblnx.bat to test on Windows and/or Linux test servers, respectively. These batch files must be customized for each use. Correct drive mappings are required. 9 Commit the updated release area to SVN. 10 Check the next build to make sure it got updated. 4.3 WebAccess Mobile Help The WebAccess Mobile help is single-sourced from the guide. WebAccess Mobile does not have context-sensitive help. The steps to generate WebAccess Mobile help are as follows: 1 In DocSys, open the.book file for the WebAccess Mobile User Guide. 2 Click Tools > Update. 3 Under Profiling, set the active profile to GenHelp, then click OK. 4 Click Tools > Export > XML. 5 Update the HTML Content Date, then click Export. 6 Navigate to the exported XML file directory (located at gw_guide_userwebmob\xml\genhelp), then double-click make_userwebmob_help.bat. This creates tablet HTML help, which is a set of HTML files in the gw_guide_userwebmob directory. 7 Watch the file creation to check for errors. 8 To see the updated help on the test server, double click copy_userwebmobwin_test.bat or copy_userwebmoblnx.bat to test on Windows and/or Linux test servers, respectively. These batch files must be customized for each use. Correct drive mappings are required. 9 Commit the updated release area to SVN. 10 Check the next build to make sure it got updated. 16 Collaboration Style Guide

17 4.4 Admin Web Console Help The Admin Web console help is HTML help that is generated from Frame. It is fully context-sensitive. 4.5 Agent Server Console Help The agent server console help is generated from Frame. For Linux, it is HTML help. For Windows, it is MS HTML help that produces a CHM file. 4.6 Agent Web Console Help The agent Web console help is generated from Frame. It is HTML help for both Linux and Windows. 4.7 Utility Help The utility help is generated from Frame. For Linux, the GWCSRGEN help is HTML help. The GWCheck help is JavaHelp, which has not been updated since GW8 because engineering packaged it up the first time and no one knows how to do it again. For Windows, both utility helps are MS HTML help, which produce CHM files. The Server Migration Utility help is Windows-only and is not currently produced from Frame. There s no development on this utility. If there ever is development, the help would need to be produced in Frame. 4.8 Free/Busy Service Configurator Help This help is generated from Frame and shares content with the Free/Busy Service part of the GroupWise/Exchange Coexistence Guide. 4.9 Synchronizer Help The next release of Data Synchronizer will become GroupWise Mobile Service 2.0 and will be part of the GroupWise product, rather than a separate product. The Synchronizer Web Admin help consists of pop-ups on many fields. The concept of real help was brought up at one point, but resources to implement it were not available. Synchronizer Web Admin will eventually be folded into the GroupWise Admin Web console, at which point it will have the same kind of context sensitive help. The Mobility Connector Monitoring tool is experimenting with a new approach to displaying online help. If it is well received, it could be a possibility for the GroupWise Admin Web console help. The Synchronizer YaST help is produced by providing the text to the YaST engineer (Mark Clark). Help System Architecture and Production 17

18 18 Collaboration Style Guide